From d112dab0d1dd0f3a81f28831ad7c5fbe66b5f2b9 Mon Sep 17 00:00:00 2001 From: Snider Date: Thu, 29 Jan 2026 09:44:28 +0000 Subject: [PATCH] docs: reorganize into docs/cmd/ and add missing commands - Move command docs to docs/cmd/ for better organization - Add work.md: multi-repo operations (health, issues, reviews, etc.) - Add docs.md: documentation management (list, sync) - Add templates.md: LinuxKit template management - Add setup.md: clone repos from registry - Update index.md with full command reference Co-Authored-By: Claude Opus 4.5 --- docs/{ => cmd}/build.md | 0 docs/{ => cmd}/dev.md | 0 docs/cmd/docs.md | 110 ++++++++++++++++++++++++++ docs/{ => cmd}/doctor.md | 0 docs/{ => cmd}/php.md | 0 docs/{ => cmd}/release.md | 0 docs/{ => cmd}/run.md | 0 docs/{ => cmd}/sdk.md | 0 docs/{ => cmd}/search.md | 0 docs/cmd/setup.md | 94 ++++++++++++++++++++++ docs/cmd/templates.md | 117 ++++++++++++++++++++++++++++ docs/cmd/work.md | 160 ++++++++++++++++++++++++++++++++++++++ docs/index.md | 61 +++++++++------ 13 files changed, 517 insertions(+), 25 deletions(-) rename docs/{ => cmd}/build.md (100%) rename docs/{ => cmd}/dev.md (100%) create mode 100644 docs/cmd/docs.md rename docs/{ => cmd}/doctor.md (100%) rename docs/{ => cmd}/php.md (100%) rename docs/{ => cmd}/release.md (100%) rename docs/{ => cmd}/run.md (100%) rename docs/{ => cmd}/sdk.md (100%) rename docs/{ => cmd}/search.md (100%) create mode 100644 docs/cmd/setup.md create mode 100644 docs/cmd/templates.md create mode 100644 docs/cmd/work.md diff --git a/docs/build.md b/docs/cmd/build.md similarity index 100% rename from docs/build.md rename to docs/cmd/build.md diff --git a/docs/dev.md b/docs/cmd/dev.md similarity index 100% rename from docs/dev.md rename to docs/cmd/dev.md diff --git a/docs/cmd/docs.md b/docs/cmd/docs.md new file mode 100644 index 00000000..083334ae --- /dev/null +++ b/docs/cmd/docs.md @@ -0,0 +1,110 @@ +# core docs + +Documentation management across repositories. + +## Usage + +```bash +core docs [flags] +``` + +## Commands + +| Command | Description | +|---------|-------------| +| `list` | List documentation across repos | +| `sync` | Sync documentation to output directory | + +## docs list + +Show documentation coverage across all repos. + +```bash +core docs list [flags] +``` + +### Flags + +| Flag | Description | +|------|-------------| +| `--registry` | Path to repos.yaml | + +### Output + +``` +Repo README CLAUDE CHANGELOG docs/ +────────────────────────────────────────────────────────────────────── +core ✓ ✓ — 12 files +core-php ✓ ✓ ✓ 8 files +core-images ✓ — — — + +Coverage: 3 with docs, 0 without +``` + +## docs sync + +Sync documentation from all repos to an output directory. + +```bash +core docs sync [flags] +``` + +### Flags + +| Flag | Description | +|------|-------------| +| `--registry` | Path to repos.yaml | +| `--output` | Output directory (default: ./docs-build) | +| `--dry-run` | Show what would be synced | + +### Output Structure + +``` +docs-build/ +└── packages/ + ├── core/ + │ ├── index.md # from README.md + │ ├── claude.md # from CLAUDE.md + │ ├── changelog.md # from CHANGELOG.md + │ ├── build.md # from docs/build.md + │ └── ... + └── core-php/ + ├── index.md + └── ... +``` + +### Example + +```bash +# Preview what will be synced +core docs sync --dry-run + +# Sync to default output +core docs sync + +# Sync to custom directory +core docs sync --output ./site/content +``` + +## What Gets Synced + +For each repo, the following files are collected: + +| Source | Destination | +|--------|-------------| +| `README.md` | `index.md` | +| `CLAUDE.md` | `claude.md` | +| `CHANGELOG.md` | `changelog.md` | +| `docs/*.md` | `*.md` | + +## Integration with core.help + +The synced docs are used to build https://core.help: + +1. Run `core docs sync --output ../core-php/docs/packages` +2. VitePress builds the combined documentation +3. Deploy to core.help + +## See Also + +- [Configuration](../configuration.md) - Project configuration diff --git a/docs/doctor.md b/docs/cmd/doctor.md similarity index 100% rename from docs/doctor.md rename to docs/cmd/doctor.md diff --git a/docs/php.md b/docs/cmd/php.md similarity index 100% rename from docs/php.md rename to docs/cmd/php.md diff --git a/docs/release.md b/docs/cmd/release.md similarity index 100% rename from docs/release.md rename to docs/cmd/release.md diff --git a/docs/run.md b/docs/cmd/run.md similarity index 100% rename from docs/run.md rename to docs/cmd/run.md diff --git a/docs/sdk.md b/docs/cmd/sdk.md similarity index 100% rename from docs/sdk.md rename to docs/cmd/sdk.md diff --git a/docs/search.md b/docs/cmd/search.md similarity index 100% rename from docs/search.md rename to docs/cmd/search.md diff --git a/docs/cmd/setup.md b/docs/cmd/setup.md new file mode 100644 index 00000000..2bcb4d1d --- /dev/null +++ b/docs/cmd/setup.md @@ -0,0 +1,94 @@ +# core setup + +Clone all repositories from the registry. + +## Usage + +```bash +core setup [flags] +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--registry` | Path to repos.yaml | +| `--path` | Base directory for cloning (default: current dir) | +| `--ssh` | Use SSH URLs instead of HTTPS | + +## Examples + +```bash +# Clone all repos from registry +core setup + +# Clone to specific directory +core setup --path ~/Code/host-uk + +# Use SSH for cloning +core setup --ssh +``` + +## Registry Format + +The registry file (`repos.yaml`) defines repositories: + +```yaml +repos: + - name: core + url: https://github.com/host-uk/core + description: Go CLI for the host-uk ecosystem + + - name: core-php + url: https://github.com/host-uk/core-php + description: PHP/Laravel packages + + - name: core-images + url: https://github.com/host-uk/core-images + description: Docker and LinuxKit images + + - name: core-api + url: https://github.com/host-uk/core-api + description: API service +``` + +## Output + +``` +Setting up host-uk workspace... + +Cloning repositories: + [1/4] core............... ✓ + [2/4] core-php........... ✓ + [3/4] core-images........ ✓ + [4/4] core-api........... ✓ + +Done! 4 repositories cloned to ~/Code/host-uk +``` + +## Finding Registry + +Core looks for `repos.yaml` in: + +1. Current directory +2. Parent directories (up to 5 levels) +3. `~/.core/repos.yaml` + +## After Setup + +```bash +# Check health of all repos +core health + +# Pull latest changes +core pull --all + +# Check CI status +core ci +``` + +## See Also + +- [work commands](work.md) - Multi-repo operations +- [search command](search.md) - Find repos on GitHub +- [install command](search.md) - Clone individual repos diff --git a/docs/cmd/templates.md b/docs/cmd/templates.md new file mode 100644 index 00000000..45730203 --- /dev/null +++ b/docs/cmd/templates.md @@ -0,0 +1,117 @@ +# core templates + +Manage LinuxKit templates for container images. + +## Usage + +```bash +core templates [command] +``` + +## Commands + +| Command | Description | +|---------|-------------| +| `list` | List available templates | +| `show` | Show template details | + +## templates list + +List all available LinuxKit templates. + +```bash +core templates list +``` + +### Output + +``` +Available Templates: + + core-dev + Full development environment with 100+ tools + Platforms: linux/amd64, linux/arm64 + + server-php + FrankenPHP production server + Platforms: linux/amd64, linux/arm64 + + edge-node + Minimal edge deployment + Platforms: linux/amd64, linux/arm64 +``` + +## templates show + +Show details of a specific template. + +```bash +core templates show +``` + +### Example + +```bash +core templates show core-dev +``` + +Output: +``` +Template: core-dev + +Description: Full development environment with 100+ tools + +Platforms: + - linux/amd64 + - linux/arm64 + +Formats: + - iso + - qcow2 + +Services: + - sshd + - docker + - frankenphp + +Size: ~1.8GB +``` + +## Template Locations + +Templates are searched in order: + +1. `.core/linuxkit/` - Project-specific +2. `~/.core/templates/` - User templates +3. Built-in templates + +## Creating Templates + +Create a LinuxKit YAML in `.core/linuxkit/`: + +```yaml +# .core/linuxkit/myserver.yml +kernel: + image: linuxkit/kernel:5.15 + cmdline: "console=tty0" + +init: + - linuxkit/init:v1.0.0 + +services: + - name: sshd + image: linuxkit/sshd:v1.0.0 + - name: myapp + image: ghcr.io/myorg/myapp:latest +``` + +Run with: + +```bash +core run --template myserver +``` + +## See Also + +- [run command](run.md) - Run LinuxKit images +- [build command](build.md) - Build LinuxKit images diff --git a/docs/cmd/work.md b/docs/cmd/work.md new file mode 100644 index 00000000..8337e435 --- /dev/null +++ b/docs/cmd/work.md @@ -0,0 +1,160 @@ +# core work + +Multi-repo git operations for managing the host-uk organization. + +## Overview + +The `work` command and related commands (`health`, `issues`, `reviews`, `commit`, `push`, `pull`, `impact`, `ci`) help manage multiple repositories in the host-uk ecosystem simultaneously. + +## Commands + +| Command | Description | +|---------|-------------| +| `core work` | Multi-repo git operations | +| `core health` | Quick health check across all repos | +| `core issues` | List open issues across all repos | +| `core reviews` | List PRs needing review | +| `core commit` | Claude-assisted commits across repos | +| `core push` | Push commits across all repos | +| `core pull` | Pull updates across all repos | +| `core impact` | Show impact of changing a repo | +| `core ci` | Check CI status across all repos | + +## core health + +Quick health check showing status of all repos. + +```bash +core health +``` + +Output shows: +- Git status (clean/dirty) +- Current branch +- Commits ahead/behind remote +- CI status + +## core issues + +List open issues across all repositories. + +```bash +core issues [flags] +``` + +### Flags + +| Flag | Description | +|------|-------------| +| `--assignee` | Filter by assignee | +| `--label` | Filter by label | +| `--limit` | Max issues per repo | + +## core reviews + +List pull requests needing review. + +```bash +core reviews [flags] +``` + +Shows PRs where: +- You are a requested reviewer +- PR is open and not draft +- CI is passing + +## core commit + +Create commits across repos with Claude assistance. + +```bash +core commit [flags] +``` + +### Flags + +| Flag | Description | +|------|-------------| +| `--message` | Commit message (auto-generated if not provided) | +| `--all` | Commit in all dirty repos | + +Claude analyzes changes and suggests conventional commit messages. + +## core push + +Push commits across all repos. + +```bash +core push [flags] +``` + +### Flags + +| Flag | Description | +|------|-------------| +| `--all` | Push all repos with unpushed commits | +| `--force` | Force push (use with caution) | + +## core pull + +Pull updates across all repos. + +```bash +core pull [flags] +``` + +### Flags + +| Flag | Description | +|------|-------------| +| `--all` | Pull all repos | +| `--rebase` | Rebase instead of merge | + +## core impact + +Show the impact of changing a repository. + +```bash +core impact +``` + +Shows: +- Dependent repos +- Reverse dependencies +- Potential breaking changes + +## core ci + +Check CI status across all repos. + +```bash +core ci [flags] +``` + +### Flags + +| Flag | Description | +|------|-------------| +| `--watch` | Watch for status changes | +| `--failing` | Show only failing repos | + +## Registry + +These commands use `repos.yaml` to know which repos to manage: + +```yaml +repos: + - name: core + path: ./core + url: https://github.com/host-uk/core + - name: core-php + path: ./core-php + url: https://github.com/host-uk/core-php +``` + +Use `core setup` to clone all repos from the registry. + +## See Also + +- [setup command](setup.md) - Clone repos from registry +- [search command](search.md) - Find and install repos diff --git a/docs/index.md b/docs/index.md index 6a37b377..b1b86c84 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,36 +18,47 @@ curl -fsSL https://github.com/host-uk/core/releases/latest/download/core-$(uname | Command | Description | |---------|-------------| -| `core build` | Build Go, Wails, Docker, and LinuxKit projects | -| `core release` | Build and publish to GitHub, npm, Homebrew, etc. | -| `core sdk` | Generate and manage API SDKs | +| [`core build`](cmd/build.md) | Build Go, Wails, Docker, and LinuxKit projects | +| [`core release`](cmd/release.md) | Build and publish to GitHub, npm, Homebrew, etc. | +| [`core sdk`](cmd/sdk.md) | Generate and manage API SDKs | ### Containers | Command | Description | |---------|-------------| -| `core run` | Run LinuxKit images with qemu/hyperkit | +| [`core run`](cmd/run.md) | Run LinuxKit images with qemu/hyperkit | | `core ps` | List running containers | | `core stop` | Stop running containers | | `core logs` | View container logs | | `core exec` | Execute commands in containers | -| `core templates` | Manage LinuxKit templates | +| [`core templates`](cmd/templates.md) | Manage LinuxKit templates | ### Development | Command | Description | |---------|-------------| -| `core dev` | Portable development environment (100+ tools) | -| `core php` | Laravel/PHP development tools | -| `core doctor` | Check development environment | +| [`core dev`](cmd/dev.md) | Portable development environment (100+ tools) | +| [`core php`](cmd/php.md) | Laravel/PHP development tools | +| [`core doctor`](cmd/doctor.md) | Check development environment | -### GitHub Integration +### GitHub & Multi-Repo | Command | Description | |---------|-------------| -| `core search` | Search GitHub for repositories | -| `core install` | Clone a repository from GitHub | -| `core setup` | Clone all repos from registry | +| [`core search`](cmd/search.md) | Search GitHub for repositories | +| [`core install`](cmd/search.md) | Clone a repository from GitHub | +| [`core setup`](cmd/setup.md) | Clone all repos from registry | +| [`core work`](cmd/work.md) | Multi-repo git operations | +| [`core health`](cmd/work.md) | Quick health check across repos | +| [`core issues`](cmd/work.md) | List open issues across repos | +| [`core reviews`](cmd/work.md) | List PRs needing review | +| [`core ci`](cmd/work.md) | Check CI status across repos | + +### Documentation + +| Command | Description | +|---------|-------------| +| [`core docs`](cmd/docs.md) | Documentation management | ## Quick Start @@ -85,19 +96,19 @@ Core uses `.core/` directory for project configuration: ## Documentation -### Build & Release -- [Build Command](build.md) - Cross-platform builds with code signing -- [Release Command](release.md) - Publishing to package managers -- [SDK Command](sdk.md) - Generate API clients from OpenAPI - -### Containers -- [Run Command](run.md) - Container management - -### Development -- [Dev Command](dev.md) - Portable development environment -- [PHP Commands](php.md) - Laravel development -- [Doctor Command](doctor.md) - Environment check -- [Search & Install](search.md) - GitHub integration +### Command Reference +- [Build](cmd/build.md) - Cross-platform builds with code signing +- [Release](cmd/release.md) - Publishing to package managers +- [SDK](cmd/sdk.md) - Generate API clients from OpenAPI +- [Run](cmd/run.md) - Container management +- [Templates](cmd/templates.md) - LinuxKit templates +- [Dev](cmd/dev.md) - Portable development environment +- [PHP](cmd/php.md) - Laravel development +- [Doctor](cmd/doctor.md) - Environment check +- [Search & Install](cmd/search.md) - GitHub integration +- [Setup](cmd/setup.md) - Clone repos from registry +- [Work](cmd/work.md) - Multi-repo operations +- [Docs](cmd/docs.md) - Documentation management ### Reference - [Configuration](configuration.md) - All config options