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

docs: add guides and fix documentation issues

Browse source 
New documentation:
- getting-started.md: installation, first build, first release
- troubleshooting.md: common errors and fixes
- workflows.md: end-to-end task sequences
- glossary.md: term definitions
- migration.md: upgrading from legacy tools

Fixes:
- Command examples: core dev task* → core ai task*
- CI flag: --were-go-for-launch → --we-are-go-for-launch
- Setup commands: core health → core dev health
- Installation: circular core go install reference
- Cross-references: broken fragment links

Improvements:
- Added complete repos.yaml documentation
- Added comprehensive environment variables reference
- Added multiple installation methods (go install, binary, source)
- Moved TODO.md to docs/.internal/

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider 2026-01-29 19:59:49 +00:00
parent 363f12f4da
commit 654f8df1ad
14 changed files with 1387 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
.claude/skills/core/SKILL.md
View file

@ -28,7 +28,7 @@ The `core` command provides a unified interface for Go/Wails development, multi-
| Build for targets | `core build --targets linux/amd64,darwin/arm64` | Cross-compile | | Build for targets | `core build --targets linux/amd64,darwin/arm64` | Cross-compile |
| Build SDK | `core build sdk` | Generate API clients from OpenAPI | | Build SDK | `core build sdk` | Generate API clients from OpenAPI |
| Preview release | `core ci` | Dry-run publish (safe default) | | Preview release | `core ci` | Dry-run publish (safe default) |
| Publish release | `core ci --were-go-for-launch` | Actually publish artifacts | | Publish release | `core ci --we-are-go-for-launch` | Actually publish artifacts |
| Check environment | `core doctor` | Verify tools installed | | Check environment | `core doctor` | Verify tools installed |
| Multi-repo status | `core dev health` | Quick summary across repos | | Multi-repo status | `core dev health` | Quick summary across repos |
| Multi-repo workflow | `core dev work` | Status + commit + push | | Multi-repo workflow | `core dev work` | Status + commit + push |
@ -82,12 +82,12 @@ core build sdk
core ci # Dry-run: shows what would be published core ci # Dry-run: shows what would be published
# Step 3: Actually publish (explicit flag required) # Step 3: Actually publish (explicit flag required)
core ci --were-go-for-launch # Actually publish to targets core ci --we-are-go-for-launch # Actually publish to targets
core ci --were-go-for-launch --draft # Publish as draft core ci --we-are-go-for-launch --draft # Publish as draft
core ci --were-go-for-launch --prerelease # Publish as prerelease core ci --we-are-go-for-launch --prerelease # Publish as prerelease
``` ```
**Why safe by default?** `core ci` always does a dry-run unless you explicitly say `--were-go-for-launch`. **Why safe by default?** `core ci` always does a dry-run unless you explicitly say `--we-are-go-for-launch`.
```bash ```bash
# Release workflow utilities # Release workflow utilities
@ -562,7 +562,7 @@ Go project?
└── Build: core build [--targets <os/arch>] └── Build: core build [--targets <os/arch>]
└── Build SDK: core build sdk └── Build SDK: core build sdk
└── Preview publish: core ci └── Preview publish: core ci
└── Publish: core ci --were-go-for-launch └── Publish: core ci --we-are-go-for-launch
PHP/Laravel project? PHP/Laravel project?
└── Start dev: core php dev [--https] └── Start dev: core php dev [--https]

2
cmd/ci/commands.go
View file

@ -5,7 +5,7 @@
// - S3-compatible storage // - S3-compatible storage
// - Custom endpoints // - Custom endpoints
// //
// Safe by default: runs in dry-run mode unless --were-go-for-launch is specified. // Safe by default: runs in dry-run mode unless --we-are-go-for-launch is specified.
// Configuration via .core/release.yaml. // Configuration via .core/release.yaml.
package ci package ci

0
docs/cmd/TODO.md → docs/.internal/TODO.md
View file

28
docs/cmd/dev/example.md
View file

@ -79,46 +79,46 @@ core dev impact core-php
```bash ```bash
# List tasks # List tasks
core dev tasks core ai tasks
# Filter by status and priority # Filter by status and priority
core dev tasks --status pending --priority high core ai tasks --status pending --priority high
# Filter by labels # Filter by labels
core dev tasks --labels bug,urgent core ai tasks --labels bug,urgent
# Show task details # Show task details
core dev task abc123 core ai task abc123
# Auto-select highest priority task # Auto-select highest priority task
core dev task --auto core ai task --auto
# Claim a task # Claim a task
core dev task abc123 --claim core ai task abc123 --claim
# Update task status # Update task status
core dev task:update abc123 --status in_progress core ai task:update abc123 --status in_progress
# Add progress notes # Add progress notes
core dev task:update abc123 --progress 50 --notes 'Halfway done' core ai task:update abc123 --progress 50 --notes 'Halfway done'
# Complete a task # Complete a task
core dev task:complete abc123 --output 'Feature implemented' core ai task:complete abc123 --output 'Feature implemented'
# Mark as failed # Mark as failed
core dev task:complete abc123 --failed --error 'Build failed' core ai task:complete abc123 --failed --error 'Build failed'
# Commit with task reference # Commit with task reference
core dev task:commit abc123 -m 'add user authentication' core ai task:commit abc123 -m 'add user authentication'
# Commit with scope and push # Commit with scope and push
core dev task:commit abc123 -m 'fix login bug' --scope auth --push core ai task:commit abc123 -m 'fix login bug' --scope auth --push
# Create PR for task # Create PR for task
core dev task:pr abc123 core ai task:pr abc123
# Create draft PR with labels # Create draft PR with labels
core dev task:pr abc123 --draft --labels 'enhancement,needs-review' core ai task:pr abc123 --draft --labels 'enhancement,needs-review'
``` ```
## Service API Management ## Service API Management

2
docs/cmd/dev/work/index.md
View file

@ -283,7 +283,7 @@ core dev impact core-php
## Registry ## Registry
These commands use `repos.yaml` to know which repos to manage. See [Configuration](example.md#registry) for format. These commands use `repos.yaml` to know which repos to manage. See [repos.yaml](../../../configuration.md#reposyaml) for format.
Use `core setup` to clone all repos from the registry. Use `core setup` to clone all repos from the registry.

4
docs/cmd/index.md
View file

@ -23,7 +23,9 @@ Unified interface for Go/PHP development, multi-repo management, and deployment.
## Installation ## Installation
```bash ```bash
core go install go install github.com/host-uk/core/cmd/core@latest
``` ```
Verify: `core doctor` Verify: `core doctor`
See [Getting Started](../getting-started.md) for all installation options.

7
docs/cmd/setup/index.md
View file

@ -191,16 +191,17 @@ Core looks for `repos.yaml` in:
```bash ```bash
# Check workspace health # Check workspace health
core health core dev health
# Full workflow (status + commit + push) # Full workflow (status + commit + push)
core work core dev work
# Build the project # Build the project
core build core build
# Run tests # Run tests
core test core go test # Go projects
core php test # PHP projects
``` ```
--- ---

142
docs/configuration.md
View file

@ -205,14 +205,148 @@ files:
port: 8080 port: 8080
``` ```
## repos.yaml
Package registry for multi-repo workspaces:
```yaml
# Organisation name (used for GitHub URLs)
org: host-uk
# Base path for cloning (default: current directory)
base_path: .
# Default settings for all repos
defaults:
ci: github
license: EUPL-1.2
branch: main
# Repository definitions
repos:
# Foundation packages (no dependencies)
core-php:
type: foundation
description: Foundation framework
core-devops:
type: foundation
description: Development environment
clone: false # Skip during setup (already exists)
# Module packages (depend on foundation)
core-tenant:
type: module
depends_on: [core-php]
description: Multi-tenancy module
core-admin:
type: module
depends_on: [core-php, core-tenant]
description: Admin panel
core-api:
type: module
depends_on: [core-php]
description: REST API framework
# Product packages (user-facing applications)
core-bio:
type: product
depends_on: [core-php, core-tenant]
description: Link-in-bio product
domain: bio.host.uk.com
core-social:
type: product
depends_on: [core-php, core-tenant]
description: Social scheduling
domain: social.host.uk.com
# Templates
core-template:
type: template
description: Starter template for new projects
```
### repos.yaml Fields
| Field | Required | Description |
|-------|----------|-------------|
| `org` | Yes | GitHub organisation name |
| `base_path` | No | Directory for cloning (default: `.`) |
| `defaults` | No | Default settings applied to all repos |
| `repos` | Yes | Map of repository definitions |
### Repository Fields
| Field | Required | Description |
|-------|----------|-------------|
| `type` | Yes | `foundation`, `module`, `product`, or `template` |
| `description` | No | Human-readable description |
| `depends_on` | No | List of package dependencies |
| `clone` | No | Set `false` to skip during setup |
| `domain` | No | Production domain (for products) |
| `branch` | No | Override default branch |
### Package Types
| Type | Description | Dependencies |
|------|-------------|--------------|
| `foundation` | Core framework packages | None |
| `module` | Reusable modules | Foundation packages |
| `product` | User-facing applications | Foundation + modules |
| `template` | Starter templates | Any |
---
## Environment Variables ## Environment Variables
Complete reference of environment variables used by Core CLI.
### Authentication
| Variable | Used By | Description |
|----------|---------|-------------|
| `GITHUB_TOKEN` | `core ci`, `core dev` | GitHub API authentication |
| `ANTHROPIC_API_KEY` | `core ai`, `core dev claude` | Claude API key |
| `AGENTIC_TOKEN` | `core ai task*` | Agentic API authentication |
| `AGENTIC_BASE_URL` | `core ai task*` | Agentic API endpoint |
### Publishing
| Variable | Used By | Description |
|----------|---------|-------------|
| `NPM_TOKEN` | `core ci` (npm publisher) | npm registry auth token |
| `CHOCOLATEY_API_KEY` | `core ci` (chocolatey publisher) | Chocolatey API key |
| `DOCKER_USERNAME` | `core ci` (docker publisher) | Docker registry username |
| `DOCKER_PASSWORD` | `core ci` (docker publisher) | Docker registry password |
### Deployment
| Variable | Used By | Description |
|----------|---------|-------------|
| `COOLIFY_URL` | `core php deploy` | Coolify server URL |
| `COOLIFY_TOKEN` | `core php deploy` | Coolify API token |
| `COOLIFY_APP_ID` | `core php deploy` | Production application ID |
| `COOLIFY_STAGING_APP_ID` | `core php deploy --staging` | Staging application ID |
### Build
| Variable | Used By | Description |
|----------|---------|-------------|
| `CGO_ENABLED` | `core build`, `core go *` | Enable/disable CGO (default: 0) |
| `GOOS` | `core build` | Target operating system |
| `GOARCH` | `core build` | Target architecture |
### Configuration Paths
| Variable | Description | | Variable | Description |
|----------|-------------| |----------|-------------|
| `GITHUB_TOKEN` | GitHub authentication (via gh CLI) | | `CORE_CONFIG` | Override config directory (default: `~/.core/`) |
| `NPM_TOKEN` | npm publish token | | `CORE_REGISTRY` | Override repos.yaml path |
| `CHOCOLATEY_API_KEY` | Chocolatey publish key |
| `COOLIFY_TOKEN` | Coolify deployment token | ---
## Defaults ## Defaults

191
docs/getting-started.md Normal file
View file

@ -0,0 +1,191 @@
# Getting Started
This guide walks you through installing Core and running your first build.
## Prerequisites
Before installing Core, ensure you have:
| Tool | Minimum Version | Check Command |
|------|-----------------|---------------|
| Go | 1.23+ | `go version` |
| Git | 2.30+ | `git --version` |
Optional (for specific features):
| Tool | Required For | Install |
|------|--------------|---------|
| `gh` | GitHub integration (`core dev issues`, `core dev reviews`) | [cli.github.com](https://cli.github.com) |
| Docker | Container builds | [docker.com](https://docker.com) |
| `task` | Task automation | `go install github.com/go-task/task/v3/cmd/task@latest` |
## Installation
### Option 1: Go Install (Recommended)
```bash
# Install latest release
go install github.com/host-uk/core/cmd/core@latest
# Verify installation
core doctor
```
If `core: command not found`, add Go's bin directory to your PATH:
```bash
export PATH="$PATH:$(go env GOPATH)/bin"
```
### Option 2: Download Binary
Download pre-built binaries from [GitHub Releases](https://github.com/host-uk/core/releases):
```bash
# macOS (Apple Silicon)
curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-darwin-arm64
chmod +x core
sudo mv core /usr/local/bin/
# macOS (Intel)
curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-darwin-amd64
chmod +x core
sudo mv core /usr/local/bin/
# Linux (x86_64)
curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-linux-amd64
chmod +x core
sudo mv core /usr/local/bin/
```
### Option 3: Build from Source
```bash
# Clone repository
git clone https://github.com/host-uk/core.git
cd core
# Build with Task (recommended)
task cli:build
# Binary at ./bin/core
# Or build with Go directly
CGO_ENABLED=0 go build -o core ./cmd/core/
sudo mv core /usr/local/bin/
```
## Your First Build
### 1. Navigate to a Go Project
```bash
cd ~/Code/my-go-project
```
### 2. Initialise Configuration
```bash
core setup
```
This detects your project type and creates configuration files in `.core/`:
- `build.yaml` - Build settings
- `release.yaml` - Release configuration
- `test.yaml` - Test commands
### 3. Build
```bash
core build
```
Output appears in `dist/`:
```
dist/
├── my-project-darwin-arm64.tar.gz
├── my-project-linux-amd64.tar.gz
└── CHECKSUMS.txt
```
### 4. Cross-Compile (Optional)
```bash
core build --targets linux/amd64,linux/arm64,darwin/arm64,windows/amd64
```
## Your First Release
Releases are **safe by default** - Core runs in dry-run mode unless you explicitly confirm.
### 1. Preview
```bash
core ci
```
This shows what would be published without actually publishing.
### 2. Publish
```bash
core ci --we-are-go-for-launch
```
This creates a GitHub release with your built artifacts.
## Multi-Repo Workflow
If you work with multiple repositories (like the host-uk ecosystem):
### 1. Clone All Repositories
```bash
mkdir host-uk && cd host-uk
core setup
```
Select packages in the interactive wizard.
### 2. Check Status
```bash
core dev health
# Output: "18 repos │ clean │ synced"
```
### 3. Work Across Repos
```bash
core dev work --status # See status table
core dev work # Commit and push all dirty repos
```
## Next Steps
| Task | Command | Documentation |
|------|---------|---------------|
| Run tests | `core go test` | [go/test](cmd/go/test/) |
| Format code | `core go fmt --fix` | [go/fmt](cmd/go/fmt/) |
| Lint code | `core go lint` | [go/lint](cmd/go/lint/) |
| PHP development | `core php dev` | [php](cmd/php/) |
| View all commands | `core --help` | [cmd](cmd/) |
## Getting Help
```bash
# Check environment
core doctor
# Command help
core <command> --help
# Full documentation
https://github.com/host-uk/core/tree/main/docs
```
## See Also
- [Configuration](configuration.md) - All config options
- [Workflows](workflows.md) - Common task sequences
- [Troubleshooting](troubleshooting.md) - When things go wrong

112
docs/glossary.md Normal file
View file

@ -0,0 +1,112 @@
# Glossary
Definitions of terms used throughout Core CLI documentation.
## A
### Artifact
A file produced by a build, typically a binary, archive, or checksum file. Artifacts are stored in the `dist/` directory and published during releases.
## C
### CGO
Go's mechanism for calling C code. Core disables CGO by default (`CGO_ENABLED=0`) to produce statically-linked binaries that don't depend on system libraries.
### Changelog
Automatically generated list of changes between releases, created from conventional commit messages. Configure in `.core/release.yaml`.
### Conventional Commits
A commit message format: `type(scope): description`. Types include `feat`, `fix`, `docs`, `chore`. Core uses this to generate changelogs.
## D
### Dry-run
A mode where commands show what they would do without actually doing it. `core ci` runs in dry-run mode by default for safety.
## F
### Foundation Package
A core package with no dependencies on other packages. Examples: `core-php`, `core-devops`. These form the base of the dependency tree.
### FrankenPHP
A modern PHP application server used by `core php dev`. Combines PHP with Caddy for high-performance serving.
## G
### `gh`
The GitHub CLI tool. Required for commands that interact with GitHub: `core dev issues`, `core dev reviews`, `core dev ci`.
## L
### LinuxKit
A toolkit for building lightweight, immutable Linux distributions. Core can build LinuxKit images via `core build --type linuxkit`.
## M
### Module (Go)
A collection of Go packages with a `go.mod` file. Core's Go commands operate on modules.
### Module (Package)
A host-uk package that depends on foundation packages. Examples: `core-tenant`, `core-admin`. Compare with **Foundation Package** and **Product**.
## P
### Package
An individual repository in the host-uk ecosystem. Packages are defined in `repos.yaml` and managed with `core pkg` commands.
### Package Index
The `repos.yaml` file that lists all packages in a workspace. Contains metadata like dependencies, type, and description.
### Product
A user-facing application package. Examples: `core-bio`, `core-social`. Products depend on foundation and module packages.
### Publisher
A release target configured in `.core/release.yaml`. Types include `github`, `docker`, `npm`, `homebrew`, `linuxkit`.
## R
### Registry (Docker/npm)
A remote repository for container images or npm packages. Core can publish to registries during releases.
### `repos.yaml`
The package index file defining all repositories in a workspace. Used by multi-repo commands like `core dev work`.
## S
### SDK
Software Development Kit. Core can generate API client SDKs from OpenAPI specs via `core build sdk`.
## T
### Target
A build target specified as `os/arch`, e.g., `linux/amd64`, `darwin/arm64`. Use `--targets` flag to specify.
## W
### Wails
A framework for building desktop applications with Go backends and web frontends. Core detects Wails projects and uses appropriate build commands.
### Workspace (Go)
A Go 1.18+ feature for working with multiple modules simultaneously. Managed via `core go work` commands.
### Workspace (Multi-repo)
A directory containing multiple packages from `repos.yaml`. Created via `core setup` and managed with `core dev` commands.
## Symbols
### `.core/`
Directory containing project configuration files:
- `build.yaml` - Build settings
- `release.yaml` - Release targets
- `test.yaml` - Test configuration
- `linuxkit/` - LinuxKit templates
### `--we-are-go-for-launch`
Flag to disable dry-run mode and actually publish a release. Named as a deliberate friction to prevent accidental releases.
---
## See Also
- [Configuration](configuration.md) - Config file reference
- [Getting Started](getting-started.md) - First-time setup

25
docs/index.md
View file

@ -5,14 +5,18 @@ Core is a unified CLI for the host-uk ecosystem - build, release, and deploy Go,
## Installation ## Installation
```bash ```bash
# From any Go project # Via Go (recommended)
core go install github.com/host-uk/core/cmd/core
# Or standard go install
go install github.com/host-uk/core/cmd/core@latest go install github.com/host-uk/core/cmd/core@latest
# Or download binary from releases
curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-$(go env GOOS)-$(go env GOARCH)
chmod +x core && sudo mv core /usr/local/bin/
# Verify
core doctor
``` ```
Verify: `core doctor` See [Getting Started](getting-started.md) for all installation options including building from source.
## Command Reference ## Command Reference
@ -47,7 +51,7 @@ core build --targets linux/amd64,darwin/arm64
# Release (dry-run by default) # Release (dry-run by default)
core ci # Preview release core ci # Preview release
core ci --were-go-for-launch # Actually publish core ci --we-are-go-for-launch # Actually publish
# Multi-repo workflow # Multi-repo workflow
core dev work # Status + commit + push core dev work # Status + commit + push
@ -71,10 +75,17 @@ Core uses `.core/` directory for project configuration:
And `repos.yaml` in workspace root for multi-repo management. And `repos.yaml` in workspace root for multi-repo management.
## Guides
- [Getting Started](getting-started.md) - Installation and first steps
- [Workflows](workflows.md) - Common task sequences
- [Troubleshooting](troubleshooting.md) - When things go wrong
- [Migration](migration.md) - Moving from legacy tools
## Reference ## Reference
- [Configuration](configuration.md) - All config options - [Configuration](configuration.md) - All config options
- [Examples](examples/) - Sample configurations - [Glossary](glossary.md) - Term definitions
## Claude Code Skill ## Claude Code Skill

233
docs/migration.md Normal file
View file

@ -0,0 +1,233 @@
# Migration Guide
Migrating from legacy scripts and tools to Core CLI.
## From push-all.sh
The `push-all.sh` script has been replaced by `core dev` commands.
| Legacy | Core CLI | Notes |
|--------|----------|-------|
| `./push-all.sh --status` | `core dev work --status` | Status table |
| `./push-all.sh --commit` | `core dev commit` | Commit dirty repos |
| `./push-all.sh` | `core dev work` | Full workflow |
### Quick Migration
```bash
# Instead of
./push-all.sh --status
# Use
core dev work --status
```
### New Features
Core CLI adds features not available in the legacy script:
```bash
# Quick health summary
core dev health
# Output: "18 repos │ clean │ synced"
# Pull repos that are behind
core dev pull
# GitHub integration
core dev issues # List open issues
core dev reviews # List PRs needing review
core dev ci # Check CI status
# Dependency analysis
core dev impact core-php # What depends on core-php?
```
---
## From Raw Go Commands
Core wraps Go commands with enhanced defaults and output.
| Raw Command | Core CLI | Benefits |
|-------------|----------|----------|
| `go test ./...` | `core go test` | Filters warnings, sets CGO_ENABLED=0 |
| `go test -coverprofile=...` | `core go cov` | HTML reports, thresholds |
| `gofmt -w .` | `core go fmt --fix` | Uses goimports if available |
| `golangci-lint run` | `core go lint` | Consistent interface |
| `go build` | `core build` | Cross-compile, sign, archive |
### Why Use Core?
```bash
# Raw go test shows linker warnings on macOS
go test ./...
# ld: warning: -no_pie is deprecated...
# Core filters noise
core go test
# PASS (clean output)
```
### Environment Setup
Core automatically sets:
- `CGO_ENABLED=0` - Static binaries
- `MACOSX_DEPLOYMENT_TARGET=26.0` - Suppress macOS warnings
- Colour output for coverage reports
---
## From Raw PHP Commands
Core orchestrates Laravel development services.
| Raw Command | Core CLI | Benefits |
|-------------|----------|----------|
| `php artisan serve` | `core php dev` | Adds Vite, Horizon, Reverb, Redis |
| `./vendor/bin/pest` | `core php test` | Auto-detects test runner |
| `./vendor/bin/pint` | `core php fmt --fix` | Consistent interface |
| Manual Coolify deploy | `core php deploy` | Tracked, scriptable |
### Development Server Comparison
```bash
# Raw: Start each service manually
php artisan serve &
npm run dev &
php artisan horizon &
php artisan reverb:start &
# Core: One command
core php dev
# Starts all services, shows unified logs
```
---
## From goreleaser
Core's release system is simpler than goreleaser for host-uk projects.
| goreleaser | Core CLI |
|------------|----------|
| `.goreleaser.yaml` | `.core/release.yaml` |
| `goreleaser release --snapshot` | `core ci` (dry-run) |
| `goreleaser release` | `core ci --we-are-go-for-launch` |
### Configuration Migration
**goreleaser:**
```yaml
builds:
- main: ./cmd/app
goos: [linux, darwin, windows]
goarch: [amd64, arm64]
archives:
- format: tar.gz
files: [LICENSE, README.md]
release:
github:
owner: host-uk
name: app
```
**Core:**
```yaml
version: 1
project:
name: app
repository: host-uk/app
targets:
- os: linux
arch: amd64
- os: darwin
arch: arm64
publishers:
- type: github
```
### Key Differences
1. **Separate build and release** - Core separates `core build` from `core ci`
2. **Safe by default** - `core ci` is dry-run unless `--we-are-go-for-launch`
3. **Simpler config** - Fewer options, sensible defaults
---
## From Manual Git Operations
Core automates multi-repo git workflows.
| Manual | Core CLI |
|--------|----------|
| `cd repo1 && git status && cd ../repo2 && ...` | `core dev work --status` |
| Check each repo for uncommitted changes | `core dev health` |
| Commit each repo individually | `core dev commit` |
| Push each repo individually | `core dev push` |
### Example: Committing Across Repos
**Manual:**
```bash
cd core-php
git add -A
git commit -m "feat: add feature"
cd ../core-tenant
git add -A
git commit -m "feat: use new feature"
# ... repeat for each repo
```
**Core:**
```bash
core dev commit
# Interactive: reviews changes, suggests messages
# Adds Co-Authored-By automatically
```
---
## Deprecated Commands
These commands have been removed or renamed:
| Deprecated | Replacement | Version |
|------------|-------------|---------|
| `core sdk generate` | `core build sdk` | v0.5.0 |
| `core dev task*` | `core ai task*` | v0.8.0 |
| `core release` | `core ci` | v0.6.0 |
---
## Version Compatibility
| Core Version | Go Version | Breaking Changes |
|--------------|------------|------------------|
| v1.0.0+ | 1.23+ | Stable API |
| v0.8.0 | 1.22+ | Task commands moved to `ai` |
| v0.6.0 | 1.22+ | Release command renamed to `ci` |
| v0.5.0 | 1.21+ | SDK generation moved to `build sdk` |
---
## Getting Help
If you encounter issues during migration:
1. Check [Troubleshooting](troubleshooting.md)
2. Run `core doctor` to verify setup
3. Use `--help` on any command: `core dev work --help`
---
## See Also
- [Getting Started](getting-started.md) - Fresh installation
- [Workflows](workflows.md) - Common task sequences
- [Configuration](configuration.md) - Config file reference

332
docs/troubleshooting.md Normal file
View file

@ -0,0 +1,332 @@
# Troubleshooting
Common issues and how to resolve them.
## Installation Issues
### "command not found: core"
**Cause:** Go's bin directory is not in your PATH.
**Fix:**
```bash
# Add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:$(go env GOPATH)/bin"
# Then reload
source ~/.bashrc # or ~/.zshrc
```
### "go: module github.com/host-uk/core: no matching versions"
**Cause:** Go module proxy hasn't cached the latest version yet.
**Fix:**
```bash
# Bypass proxy
GOPROXY=direct go install github.com/host-uk/core/cmd/core@latest
```
---
## Build Issues
### "no Go files in..."
**Cause:** Core couldn't find a main package to build.
**Fix:**
1. Check you're in the correct directory
2. Ensure `.core/build.yaml` has the correct `main` path:
```yaml
project:
main: ./cmd/myapp # Path to main package
```
### "CGO_ENABLED=1 but no C compiler"
**Cause:** Build requires CGO but no C compiler is available.
**Fix:**
```bash
# Option 1: Disable CGO (if not needed)
core build # Core disables CGO by default
# Option 2: Install a C compiler
# macOS
xcode-select --install
# Ubuntu/Debian
sudo apt install build-essential
# Windows
# Install MinGW or use WSL
```
### Build succeeds but binary doesn't run
**Cause:** Built for wrong architecture.
**Fix:**
```bash
# Check what you built
file dist/myapp-*
# Build for your current platform
core build --targets $(go env GOOS)/$(go env GOARCH)
```
---
## Release Issues
### "dry-run mode, use --we-are-go-for-launch to publish"
**This is expected behaviour.** Core runs in dry-run mode by default for safety.
**To actually publish:**
```bash
core ci --we-are-go-for-launch
```
### "failed to create release: 401 Unauthorized"
**Cause:** GitHub token missing or invalid.
**Fix:**
```bash
# Authenticate with GitHub CLI
gh auth login
# Or set token directly
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
```
### "no artifacts found in dist/"
**Cause:** You need to build before releasing.
**Fix:**
```bash
# Build first
core build
# Then release
core ci --we-are-go-for-launch
```
### "tag already exists"
**Cause:** Trying to release a version that's already been released.
**Fix:**
1. Update version in your code/config
2. Or delete the existing tag (if intentional):
```bash
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
```
---
## Multi-Repo Issues
### "repos.yaml not found"
**Cause:** Core can't find the package registry.
**Fix:**
Core looks for `repos.yaml` in:
1. Current directory
2. Parent directories (walking up to root)
3. `~/Code/host-uk/repos.yaml`
4. `~/.config/core/repos.yaml`
Either:
- Run commands from a directory with `repos.yaml`
- Use `--registry /path/to/repos.yaml`
- Run `core setup` to bootstrap a new workspace
### "failed to clone: Permission denied (publickey)"
**Cause:** SSH key not configured for GitHub.
**Fix:**
```bash
# Check SSH connection
ssh -T git@github.com
# If that fails, add your key
ssh-add ~/.ssh/id_ed25519
# Or configure SSH
# See: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
```
### "repository not found" during setup
**Cause:** You don't have access to the repository, or it doesn't exist.
**Fix:**
1. Check you're authenticated: `gh auth status`
2. Verify the repo exists and you have access
3. For private repos, ensure your token has `repo` scope
---
## GitHub Integration Issues
### "gh: command not found"
**Cause:** GitHub CLI not installed.
**Fix:**
```bash
# macOS
brew install gh
# Ubuntu/Debian
sudo apt install gh
# Windows
winget install GitHub.cli
# Then authenticate
gh auth login
```
### "core dev issues" shows nothing
**Possible causes:**
1. No open issues exist
2. Not authenticated with GitHub
3. Not in a directory with `repos.yaml`
**Fix:**
```bash
# Check auth
gh auth status
# Check you're in a workspace
ls repos.yaml
# Show all issues including closed
core dev issues --all
```
---
## PHP Issues
### "frankenphp: command not found"
**Cause:** FrankenPHP not installed.
**Fix:**
```bash
# macOS
brew install frankenphp
# Or use Docker
core php dev --docker
```
### "core php dev" exits immediately
**Cause:** Usually a port conflict or missing dependency.
**Fix:**
```bash
# Check if port 8000 is in use
lsof -i :8000
# Try a different port
core php dev --port 9000
# Check logs for errors
core php logs
```
---
## Performance Issues
### Commands are slow
**Possible causes:**
1. Large number of repositories
2. Network latency to GitHub
3. Go module downloads
**Fix:**
```bash
# For multi-repo commands, use health for quick check
core dev health # Fast summary
# Instead of
core dev work --status # Full table (slower)
# Pre-download Go modules
go mod download
```
---
## Getting More Help
### Enable Verbose Output
Most commands support `-v` or `--verbose`:
```bash
core build -v
core go test -v
```
### Check Environment
```bash
core doctor
```
This verifies all required tools are installed and configured.
### Report Issues
If you've found a bug:
1. Check existing issues: https://github.com/host-uk/core/issues
2. Create a new issue with:
- Core version (`core --version`)
- OS and architecture (`go env GOOS GOARCH`)
- Command that failed
- Full error output
---
## See Also
- [Getting Started](getting-started.md) - Installation and first steps
- [Configuration](configuration.md) - Config file reference
- [doctor](cmd/doctor/) - Environment verification

334
docs/workflows.md Normal file
View file

@ -0,0 +1,334 @@
# Workflows
Common end-to-end workflows for Core CLI.
## Go Project: Build and Release
Complete workflow from code to GitHub release.
```bash
# 1. Run tests
core go test
# 2. Check coverage
core go cov --threshold 80
# 3. Format and lint
core go fmt --fix
core go lint
# 4. Build for all platforms
core build --targets linux/amd64,linux/arm64,darwin/arm64,windows/amd64
# 5. Preview release (dry-run)
core ci
# 6. Publish
core ci --we-are-go-for-launch
```
**Output structure:**
```
dist/
├── myapp-darwin-arm64.tar.gz
├── myapp-linux-amd64.tar.gz
├── myapp-linux-arm64.tar.gz
├── myapp-windows-amd64.zip
└── CHECKSUMS.txt
```
---
## PHP Project: Development to Deployment
Local development through to production deployment.
```bash
# 1. Start development environment
core php dev
# 2. Run tests (in another terminal)
core php test --parallel
# 3. Check code quality
core php fmt --fix
core php analyse
# 4. Deploy to staging
core php deploy --staging --wait
# 5. Verify staging
# (manual testing)
# 6. Deploy to production
core php deploy --wait
# 7. Monitor
core php deploy:status
```
**Rollback if needed:**
```bash
core php deploy:rollback
```
---
## Multi-Repo: Daily Workflow
Working across the host-uk monorepo.
### Morning: Sync Everything
```bash
# Quick health check
core dev health
# Pull all repos that are behind
core dev pull --all
# Check for issues assigned to you
core dev issues --assignee @me
```
### During Development
```bash
# Work on code...
# Check status across all repos
core dev work --status
# Commit changes (Claude-assisted messages)
core dev commit
# Push when ready
core dev push
```
### End of Day
```bash
# Full workflow: status → commit → push
core dev work
# Check CI status
core dev ci
# Review any failed builds
core dev ci --failed
```
---
## New Developer: Environment Setup
First-time setup for a new team member.
```bash
# 1. Verify prerequisites
core doctor
# 2. Create workspace directory
mkdir ~/Code/host-uk && cd ~/Code/host-uk
# 3. Bootstrap workspace (interactive)
core setup
# 4. Select packages in wizard
# Use arrow keys, space to select, enter to confirm
# 5. Verify setup
core dev health
# 6. Start working
core dev work --status
```
---
## CI Pipeline: Automated Build
Example GitHub Actions workflow.
```yaml
# .github/workflows/release.yml
name: Release
on:
push:
tags:
- 'v*'
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.23'
- name: Install Core
run: go install github.com/host-uk/core/cmd/core@latest
- name: Build
run: core build --ci
- name: Release
run: core ci --we-are-go-for-launch
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
---
## SDK Generation: API Client Updates
Generate SDK clients when API changes.
```bash
# 1. Validate OpenAPI spec
core sdk validate
# 2. Check for breaking changes
core sdk diff --base v1.0.0
# 3. Generate SDKs
core build sdk
# 4. Review generated code
git diff
# 5. Commit if satisfied
git add -A && git commit -m "chore: regenerate SDK clients"
```
---
## Dependency Update: Cross-Repo Change
When updating a shared package like `core-php`.
```bash
# 1. Make changes in core-php
cd ~/Code/host-uk/core-php
# ... edit code ...
# 2. Run tests
core go test # or core php test
# 3. Check what depends on core-php
core dev impact core-php
# Output:
# core-tenant (direct)
# core-admin (via core-tenant)
# core-api (direct)
# ...
# 4. Commit core-php changes
core dev commit
# 5. Update dependent packages
cd ~/Code/host-uk
for pkg in core-tenant core-admin core-api; do
cd $pkg
composer update host-uk/core-php
core php test
cd ..
done
# 6. Commit all updates
core dev work
```
---
## Hotfix: Emergency Production Fix
Fast path for critical fixes.
```bash
# 1. Create hotfix branch
git checkout -b hotfix/critical-bug main
# 2. Make fix
# ... edit code ...
# 3. Test
core go test --run TestCriticalPath
# 4. Build
core build
# 5. Preview release
core ci --prerelease
# 6. Publish hotfix
core ci --we-are-go-for-launch --prerelease
# 7. Merge back to main
git checkout main
git merge hotfix/critical-bug
git push
```
---
## Documentation: Sync Across Repos
Keep documentation synchronised.
```bash
# 1. List all docs
core docs list
# 2. Sync to central location
core docs sync --output ./docs-site
# 3. Review changes
git diff docs-site/
# 4. Commit
git add docs-site/
git commit -m "docs: sync from packages"
```
---
## Troubleshooting: Failed Build
When a build fails.
```bash
# 1. Check environment
core doctor
# 2. Clean previous artifacts
rm -rf dist/
# 3. Verbose build
core build -v
# 4. If Go-specific issues
core go mod tidy
core go mod verify
# 5. Check for test failures
core go test -v
# 6. Review configuration
cat .core/build.yaml
```
---
## See Also
- [Getting Started](getting-started.md) - First-time setup
- [Troubleshooting](troubleshooting.md) - When things go wrong
- [Configuration](configuration.md) - Config file reference