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 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
229cde534d
commit
d112dab0d1
13 changed files with 517 additions and 25 deletions
110
docs/cmd/docs.md
Normal file
110
docs/cmd/docs.md
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
# core docs
|
||||
|
||||
Documentation management across repositories.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
core docs <command> [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
|
||||
94
docs/cmd/setup.md
Normal file
94
docs/cmd/setup.md
Normal file
|
|
@ -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
|
||||
117
docs/cmd/templates.md
Normal file
117
docs/cmd/templates.md
Normal file
|
|
@ -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 <name>
|
||||
```
|
||||
|
||||
### 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
|
||||
160
docs/cmd/work.md
Normal file
160
docs/cmd/work.md
Normal file
|
|
@ -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 <repo>
|
||||
```
|
||||
|
||||
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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue