From ace63062337e989039b98824795eaf434e0c9f01 Mon Sep 17 00:00:00 2001 From: Snider Date: Thu, 29 Jan 2026 14:46:31 +0000 Subject: [PATCH] docs: restructure cmd docs to mirror CLI hierarchy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Convert flat .md files to index.md in subdirectories - Add subcommand directories (go/test, go/cov, build/sdk, etc.) - Update dev/index.md to include multi-repo commands - Structure now mirrors: core [subcmd] → docs/cmd/// Co-Authored-By: Claude Opus 4.5 --- docs/cmd/build.md | 171 ------------------ docs/cmd/{release.md => ci/index.md} | 0 docs/cmd/{dev.md => dev/index.md} | 46 +++-- docs/cmd/{work.md => dev/work/index.md} | 0 docs/cmd/{docs.md => docs/index.md} | 0 docs/cmd/{doctor.md => doctor/index.md} | 0 docs/cmd/go/cov/index.md | 28 +++ docs/cmd/go/fmt/index.md | 24 +++ docs/cmd/go/index.md | 14 ++ docs/cmd/go/install/index.md | 24 +++ docs/cmd/go/lint/index.md | 22 +++ docs/cmd/go/mod/index.md | 21 +++ docs/cmd/go/test/index.md | 31 ++++ docs/cmd/index.md | 27 +++ docs/cmd/{php.md => php/index.md} | 0 docs/cmd/pkg/index.md | 13 ++ docs/cmd/{search.md => pkg/search/index.md} | 0 docs/cmd/run.md | 132 -------------- docs/cmd/{sdk.md => sdk/index.md} | 0 docs/cmd/{setup.md => setup/index.md} | 0 docs/cmd/test/index.md | 5 + docs/cmd/vm/index.md | 14 ++ .../{templates.md => vm/templates/index.md} | 0 23 files changed, 254 insertions(+), 318 deletions(-) delete mode 100644 docs/cmd/build.md rename docs/cmd/{release.md => ci/index.md} (100%) rename docs/cmd/{dev.md => dev/index.md} (84%) rename docs/cmd/{work.md => dev/work/index.md} (100%) rename docs/cmd/{docs.md => docs/index.md} (100%) rename docs/cmd/{doctor.md => doctor/index.md} (100%) create mode 100644 docs/cmd/go/cov/index.md create mode 100644 docs/cmd/go/fmt/index.md create mode 100644 docs/cmd/go/index.md create mode 100644 docs/cmd/go/install/index.md create mode 100644 docs/cmd/go/lint/index.md create mode 100644 docs/cmd/go/mod/index.md create mode 100644 docs/cmd/go/test/index.md create mode 100644 docs/cmd/index.md rename docs/cmd/{php.md => php/index.md} (100%) create mode 100644 docs/cmd/pkg/index.md rename docs/cmd/{search.md => pkg/search/index.md} (100%) delete mode 100644 docs/cmd/run.md rename docs/cmd/{sdk.md => sdk/index.md} (100%) rename docs/cmd/{setup.md => setup/index.md} (100%) create mode 100644 docs/cmd/test/index.md create mode 100644 docs/cmd/vm/index.md rename docs/cmd/{templates.md => vm/templates/index.md} (100%) diff --git a/docs/cmd/build.md b/docs/cmd/build.md deleted file mode 100644 index 12c7d054..00000000 --- a/docs/cmd/build.md +++ /dev/null @@ -1,171 +0,0 @@ -# core build - -Build Go, Wails, Docker, and LinuxKit projects with automatic project detection. - -## 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/release.md b/docs/cmd/ci/index.md similarity index 100% rename from docs/cmd/release.md rename to docs/cmd/ci/index.md diff --git a/docs/cmd/dev.md b/docs/cmd/dev/index.md similarity index 84% rename from docs/cmd/dev.md rename to docs/cmd/dev/index.md index 696d457d..e65713cb 100644 --- a/docs/cmd/dev.md +++ b/docs/cmd/dev/index.md @@ -1,24 +1,40 @@ # core dev -Portable development environment with 100+ embedded tools. +Multi-repo development workflow and portable dev environment. -## Overview - -Core DevOps provides a sandboxed, immutable development environment based on LinuxKit. It includes AI tools (Claude, Gemini), runtimes (Go, Node, PHP, Python, Rust), and infrastructure tools (Docker, Kubernetes, Terraform). - -## Commands +## Multi-Repo Commands | Command | Description | |---------|-------------| -| `install` | Download the core-devops image for your platform | -| `boot` | Start the development environment | -| `stop` | Stop the running environment | -| `status` | Show environment status | -| `shell` | Open a shell in the environment | -| `serve` | Mount project and start dev server | -| `test` | Run tests inside the environment | -| `claude` | Start sandboxed Claude session | -| `update` | Update to latest image | +| [work](work/) | Full workflow: status + commit + push | +| [health](health/) | Quick health check across repos | +| [commit](commit/) | Claude-assisted commits | +| [push](push/) | Push repos with unpushed commits | +| [pull](pull/) | Pull repos that are behind | +| [issues](issues/) | List open issues | +| [reviews](reviews/) | List PRs needing review | +| [ci](ci/) | Check CI status | +| [impact](impact/) | Show dependency impact | + +## Dev Environment Commands + +| Command | Description | +|---------|-------------| +| [install](install/) | Download the core-devops image | +| [boot](boot/) | Start the environment | +| [stop](stop/) | Stop the environment | +| [status](status/) | Show status | +| [shell](shell/) | Open shell | +| [serve](serve/) | Start dev server | +| [test](test/) | Run tests | +| [claude](claude/) | Sandboxed Claude | +| [update](update/) | Update image | + +--- + +## Dev Environment Overview + +Core DevOps provides a sandboxed, immutable development environment based on LinuxKit with 100+ embedded tools. ## Quick Start diff --git a/docs/cmd/work.md b/docs/cmd/dev/work/index.md similarity index 100% rename from docs/cmd/work.md rename to docs/cmd/dev/work/index.md diff --git a/docs/cmd/docs.md b/docs/cmd/docs/index.md similarity index 100% rename from docs/cmd/docs.md rename to docs/cmd/docs/index.md diff --git a/docs/cmd/doctor.md b/docs/cmd/doctor/index.md similarity index 100% rename from docs/cmd/doctor.md rename to docs/cmd/doctor/index.md diff --git a/docs/cmd/go/cov/index.md b/docs/cmd/go/cov/index.md new file mode 100644 index 00000000..a970b330 --- /dev/null +++ b/docs/cmd/go/cov/index.md @@ -0,0 +1,28 @@ +# core go cov + +Generate coverage report with thresholds. + +## Usage + +```bash +core go cov [flags] +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--pkg` | Package to test (default: `./...`) | +| `--html` | Generate HTML report | +| `--open` | Open in browser | +| `--threshold` | Fail if coverage below % | + +## Examples + +```bash +core go cov # Summary +core go cov --html # HTML report +core go cov --open # Open in browser +core go cov --threshold 80 # Fail if < 80% +core go cov --pkg ./pkg/release # Specific package +``` diff --git a/docs/cmd/go/fmt/index.md b/docs/cmd/go/fmt/index.md new file mode 100644 index 00000000..48aa0590 --- /dev/null +++ b/docs/cmd/go/fmt/index.md @@ -0,0 +1,24 @@ +# core go fmt + +Format Go code using goimports or gofmt. + +## Usage + +```bash +core go fmt [flags] +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--fix` | Apply fixes (default: check only) | +| `--diff` | Show diff | + +## Examples + +```bash +core go fmt # Check +core go fmt --fix # Apply fixes +core go fmt --diff # Show diff +``` diff --git a/docs/cmd/go/index.md b/docs/cmd/go/index.md new file mode 100644 index 00000000..c42423cf --- /dev/null +++ b/docs/cmd/go/index.md @@ -0,0 +1,14 @@ +# core go + +Go development tools. + +## Subcommands + +| Command | Description | +|---------|-------------| +| [test](test/) | Run tests | +| [cov](cov/) | Coverage report | +| [fmt](fmt/) | Format code | +| [lint](lint/) | Lint code | +| [install](install/) | Install binary | +| [mod](mod/) | Module management | diff --git a/docs/cmd/go/install/index.md b/docs/cmd/go/install/index.md new file mode 100644 index 00000000..c67ec84d --- /dev/null +++ b/docs/cmd/go/install/index.md @@ -0,0 +1,24 @@ +# core go install + +Install Go binary with auto-detection. + +## Usage + +```bash +core go install [path] [flags] +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--no-cgo` | Disable CGO | +| `-v` | Verbose | + +## Examples + +```bash +core go install # Auto-detect cmd/ +core go install ./cmd/core # Specific path +core go install --no-cgo # Pure Go +``` diff --git a/docs/cmd/go/lint/index.md b/docs/cmd/go/lint/index.md new file mode 100644 index 00000000..cf25206d --- /dev/null +++ b/docs/cmd/go/lint/index.md @@ -0,0 +1,22 @@ +# core go lint + +Run golangci-lint. + +## Usage + +```bash +core go lint [flags] +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--fix` | Auto-fix issues | + +## Examples + +```bash +core go lint # Check +core go lint --fix # Auto-fix +``` diff --git a/docs/cmd/go/mod/index.md b/docs/cmd/go/mod/index.md new file mode 100644 index 00000000..14b2e41d --- /dev/null +++ b/docs/cmd/go/mod/index.md @@ -0,0 +1,21 @@ +# core go mod + +Module management. + +## Subcommands + +| Command | Description | +|---------|-------------| +| `tidy` | Tidy go.mod | +| `download` | Download dependencies | +| `verify` | Verify dependencies | +| `graph` | Show dependency graph | + +## Examples + +```bash +core go mod tidy +core go mod download +core go mod verify +core go mod graph +``` diff --git a/docs/cmd/go/test/index.md b/docs/cmd/go/test/index.md new file mode 100644 index 00000000..068131c3 --- /dev/null +++ b/docs/cmd/go/test/index.md @@ -0,0 +1,31 @@ +# core go test + +Run Go tests with coverage and filtered output. + +## Usage + +```bash +core go test [flags] +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--pkg` | Package to test (default: `./...`) | +| `--run` | Run specific tests | +| `--short` | Skip long-running tests | +| `--race` | Enable race detection | +| `--coverage` | Show coverage summary | +| `--json` | JSON output for CI | +| `-v` | Verbose output | + +## Examples + +```bash +core go test # All tests +core go test --pkg ./pkg/core # Specific package +core go test --run TestHash # Specific test +core go test --coverage # With coverage +core go test --race # Race detection +``` diff --git a/docs/cmd/index.md b/docs/cmd/index.md new file mode 100644 index 00000000..aa229709 --- /dev/null +++ b/docs/cmd/index.md @@ -0,0 +1,27 @@ +# Core CLI + +Unified interface for Go/PHP development, multi-repo management, and deployment. + +## Commands + +| Command | Description | +|---------|-------------| +| [go](go/) | Go development tools | +| [php](php/) | Laravel/PHP development tools | +| [build](build/) | Build projects | +| [ci](ci/) | Publish releases | +| [sdk](sdk/) | SDK validation | +| [dev](dev/) | Multi-repo workflow + dev environment | +| [pkg](pkg/) | Package management | +| [vm](vm/) | LinuxKit VM management | +| [docs](docs/) | Documentation management | +| [setup](setup/) | Clone repos | +| [doctor](doctor/) | Check environment | + +## Installation + +```bash +core go install +``` + +Verify: `core doctor` diff --git a/docs/cmd/php.md b/docs/cmd/php/index.md similarity index 100% rename from docs/cmd/php.md rename to docs/cmd/php/index.md diff --git a/docs/cmd/pkg/index.md b/docs/cmd/pkg/index.md new file mode 100644 index 00000000..cf97ad21 --- /dev/null +++ b/docs/cmd/pkg/index.md @@ -0,0 +1,13 @@ +# core pkg + +Package management for core-* repos. + +## Subcommands + +| Command | Description | +|---------|-------------| +| [search](search/) | Search packages | +| [install](install/) | Install package | +| [list](list/) | List installed | +| [update](update/) | Update packages | +| [outdated](outdated/) | Check outdated | diff --git a/docs/cmd/search.md b/docs/cmd/pkg/search/index.md similarity index 100% rename from docs/cmd/search.md rename to docs/cmd/pkg/search/index.md diff --git a/docs/cmd/run.md b/docs/cmd/run.md deleted file mode 100644 index 1e760ce3..00000000 --- a/docs/cmd/run.md +++ /dev/null @@ -1,132 +0,0 @@ -# core run - -Run LinuxKit images with qemu or hyperkit. - -## Usage - -```bash -core run [flags] -``` - -## Flags - -| Flag | Description | -|------|-------------| -| `-d, --detach` | Run in background | -| `--cpus` | Number of CPUs (default: 1) | -| `--mem` | Memory in MB (default: 1024) | -| `--disk` | Disk size (default: none) | -| `--template` | Use built-in template | - -## Examples - -### Run ISO Image - -```bash -# Run LinuxKit ISO -core run server.iso - -# With more resources -core run server.iso --cpus 2 --mem 2048 - -# Detached mode -core run server.iso -d -``` - -### Run from Template - -```bash -# List available templates -core templates - -# Run template -core run --template core-dev -``` - -### Formats - -Supported image formats: -- `.iso` - Bootable ISO -- `.qcow2` - QEMU disk image -- `.raw` - Raw disk image -- `.vmdk` - VMware disk - -## Container Management - -```bash -# List running containers -core ps - -# View logs -core logs - -# Follow logs -core logs -f - -# Execute command -core exec - -# Stop container -core stop -``` - -## Templates - -Built-in templates in `.core/linuxkit/`: - -| Template | Description | -|----------|-------------| -| `core-dev` | Development environment | -| `server-php` | FrankenPHP server | - -### Custom Templates - -Create `.core/linuxkit/mytemplate.yml`: - -```yaml -kernel: - image: linuxkit/kernel:6.6 - cmdline: "console=tty0" - -init: - - linuxkit/init:latest - - linuxkit/runc:latest - - linuxkit/containerd:latest - -services: - - name: myservice - image: myorg/myservice:latest - -files: - - path: /etc/myconfig - contents: | - key: value -``` - -Then run: - -```bash -core run --template mytemplate -``` - -## Networking - -LinuxKit VMs get their own network namespace. Port forwarding: - -```bash -# Forward port 8080 -core run server.iso -p 8080:80 - -# Multiple ports -core run server.iso -p 8080:80 -p 8443:443 -``` - -## Disk Persistence - -```bash -# Create persistent disk -core run server.iso --disk 10G - -# Attach existing disk -core run server.iso --disk /path/to/disk.qcow2 -``` diff --git a/docs/cmd/sdk.md b/docs/cmd/sdk/index.md similarity index 100% rename from docs/cmd/sdk.md rename to docs/cmd/sdk/index.md diff --git a/docs/cmd/setup.md b/docs/cmd/setup/index.md similarity index 100% rename from docs/cmd/setup.md rename to docs/cmd/setup/index.md diff --git a/docs/cmd/test/index.md b/docs/cmd/test/index.md new file mode 100644 index 00000000..dbf2b2ce --- /dev/null +++ b/docs/cmd/test/index.md @@ -0,0 +1,5 @@ +# core test + +Run tests (legacy command). + +**Prefer:** `core go test` or `core php test` diff --git a/docs/cmd/vm/index.md b/docs/cmd/vm/index.md new file mode 100644 index 00000000..88257faa --- /dev/null +++ b/docs/cmd/vm/index.md @@ -0,0 +1,14 @@ +# core vm + +LinuxKit VM management. + +## Subcommands + +| Command | Description | +|---------|-------------| +| [run](run/) | Run VM | +| [ps](ps/) | List VMs | +| [stop](stop/) | Stop VM | +| [logs](logs/) | View logs | +| [exec](exec/) | Execute command | +| [templates](templates/) | Manage templates | diff --git a/docs/cmd/templates.md b/docs/cmd/vm/templates/index.md similarity index 100% rename from docs/cmd/templates.md rename to docs/cmd/vm/templates/index.md