core/php-devops
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 4

docs: add VitePress documentation with GitHub Pages deployment

Browse source 
- VitePress config with canonical URLs to core.help
- Developer preview banner linking to main docs
- Documentation pages: quick-start, commands, core-folder, repos-yaml
- GitHub Actions workflow for Pages deployment

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider 2026-01-31 20:28:07 +00:00
parent 8a921dfb2d
commit 97aab0fcca
12 changed files with 768 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

59
.github/workflows/docs.yml vendored Normal file
View file

@ -0,0 +1,59 @@
name: Deploy Docs
on:
push:
branches: [dev, main]
paths:
- 'doc/**'
- '.vitepress/**'
- 'package.json'
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Install dependencies
run: npm install
- name: Build with VitePress
run: npm run docs:build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: .vitepress/dist
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
needs: build
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4

78
.vitepress/config.ts Normal file
View file

@ -0,0 +1,78 @@
import { defineConfig } from 'vitepress'
const pkg = 'devops'
const canonical = `https://core.help/packages/${pkg}/`
export default defineConfig({
title: 'Host UK DevOps',
description: 'Developer workspace orchestrator for Host UK',
srcDir: 'doc',
outDir: '.vitepress/dist',
head: [
['link', { rel: 'canonical', href: canonical }],
['meta', { property: 'og:site_name', content: 'Host UK Documentation' }],
],
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'core.help', link: 'https://core.help' },
],
sidebar: [
{
text: 'Guide',
items: [
{ text: 'Introduction', link: '/' },
{ text: 'Quick Start', link: '/quick-start' },
{ text: 'Commands', link: '/commands' },
]
},
{
text: 'Configuration',
items: [
{ text: '.core/ Folder', link: '/core-folder' },
{ text: 'repos.yaml', link: '/repos-yaml' },
]
},
{
text: 'Reference',
items: [
{ text: 'Package Types', link: '/package-types' },
{ text: 'Troubleshooting', link: '/troubleshooting' },
]
}
],
socialLinks: [
{ icon: 'github', link: 'https://github.com/host-uk/core-devops' }
],
footer: {
message: 'Released under the EUPL-1.2 License.',
copyright: 'Copyright © Host UK'
},
search: {
provider: 'local'
},
editLink: {
pattern: 'https://github.com/host-uk/core-devops/edit/dev/doc/:path',
text: 'Edit this page on GitHub'
}
},
sitemap: {
hostname: canonical
},
transformHead({ pageData }) {
const head: any[] = []
const pagePath = pageData.relativePath.replace(/\.md$/, '.html').replace(/index\.html$/, '')
head.push(['link', { rel: 'canonical', href: `${canonical}${pagePath}` }])
return head
}
})

33
.vitepress/theme/custom.css Normal file
View file

@ -0,0 +1,33 @@
.dev-banner {
background: linear-gradient(90deg, #7c3aed 0%, #2563eb 100%);
color: white;
padding: 0.5rem 1rem;
text-align: center;
font-size: 0.875rem;
position: sticky;
top: 0;
z-index: 100;
}
.dev-banner a {
color: #fbbf24;
font-weight: 600;
text-decoration: underline;
}
.dev-banner a:hover {
color: #fcd34d;
}
.VPNav {
top: 36px !important;
}
.VPSidebar {
top: calc(var(--vp-nav-height) + 36px) !important;
height: calc(100vh - var(--vp-nav-height) - 36px) !important;
}
.VPContent {
padding-top: 36px;
}

21
.vitepress/theme/index.ts Normal file
View file

@ -0,0 +1,21 @@
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import type { Theme } from 'vitepress'
import './custom.css'
const Banner = () => {
return h('div', { class: 'dev-banner' }, [
h('span', '📚 Developer preview. '),
h('a', { href: 'https://core.help/packages/devops/', target: '_blank' }, 'Visit core.help'),
h('span', ' for the complete documentation.')
])
}
export default {
extends: DefaultTheme,
Layout() {
return h(DefaultTheme.Layout, null, {
'layout-top': () => h(Banner)
})
}
} satisfies Theme

134
doc/commands.md Normal file
View file

@ -0,0 +1,134 @@
# Commands Reference
All `core` CLI commands available in the workspace.
## Workspace Commands
### `core health`
Quick status summary of all repos.
```bash
core health
# Output: 18 repos │ 2 dirty │ synced
```
### `core work`
Full workflow: status → commit → push.
```bash
core work # Interactive
core work --status # Status table only
```
### `core commit`
Claude-assisted commits for dirty repos.
```bash
core commit # Interactive
core commit --all # Commit all without prompting
```
### `core push`
Push repos with unpushed commits.
```bash
core push # Interactive
core push --force # Push without confirmation
```
### `core pull`
Pull repos that are behind.
```bash
core pull # Interactive
core pull --all # Pull all repos
```
## GitHub Integration
### `core issues`
List open issues across repos.
```bash
core issues # All open issues
core issues --assignee @me # Assigned to you
```
### `core reviews`
List PRs needing review.
```bash
core reviews
```
### `core ci`
GitHub Actions workflow status.
```bash
core ci
```
## Analysis
### `core impact`
Show what depends on a package.
```bash
core impact core-php
```
## Package Commands
### `core php test`
Run Pest tests in the active package.
```bash
core php test
core php test --filter=ClassName
```
### `core php lint`
Run Pint linter in the active package.
```bash
core php lint
```
### `core php dev`
Start Vite dev server in the active package.
```bash
core php dev
```
## Setup Commands
### `core setup`
Clone repos into the workspace.
```bash
core setup # Default (foundation + module)
core setup --only foundation,module # Specific types
```
### `core doctor`
Check environment health.
```bash
core doctor # Check only
core doctor --fix # Attempt to fix issues
```

80
doc/core-folder.md Normal file
View file

@ -0,0 +1,80 @@
# .core/ Folder
The `.core/` folder provides workspace configuration and Claude Code integration.
## Structure
```
.core/
├── workspace.yaml # Workspace configuration
├── plugin/
│ ├── plugin.json # Claude Code manifest
│ ├── skills/ # Context-aware skills
│ └── hooks/ # Command hooks
└── docs/
└── core-folder-spec.md # Full specification
```
## workspace.yaml
Defines the active package and workspace settings.
```yaml
version: 1
# Active package for `core php test`, etc.
active: core-php
# Default package types for `core setup`
default_only:
- foundation
- module
# Paths
packages_dir: ./packages
# Settings
settings:
suggest_core_commands: true
show_active_in_prompt: true
```
## Changing Active Package
Edit `.core/workspace.yaml`:
```yaml
active: core-tenant
```
Then commands run from workspace root target that package:
```bash
core php test # Now runs in core-tenant
```
## Claude Code Plugin
The `plugin/` folder integrates with Claude Code:
### plugin.json
Manifest defining skills and commands.
### skills/
Markdown files providing context-aware guidance:
- `workspace.md` - Multi-repo navigation
- `switch-package.md` - Package switching
- `package-status.md` - Status checking
### hooks/
Shell scripts that run before/after commands:
- `prefer-core.sh` - Suggests `core` commands
## Full Specification
See `.core/docs/core-folder-spec.md` for the complete specification that packages should follow.

56
doc/index.md Normal file
View file

@ -0,0 +1,56 @@
---
layout: home
hero:
name: "core-devops"
text: "Developer Workspace"
tagline: Unified entry point for Host UK development
actions:
- theme: brand
text: Quick Start
link: /quick-start
- theme: alt
text: View on GitHub
link: https://github.com/host-uk/core-devops
features:
- title: One Command Setup
details: Clone and run `make setup` to get a complete development environment with all dependencies.
- title: Multi-Repo Management
details: Manage 18+ Laravel packages from a single workspace using the `core` CLI.
- title: Agentic-First
details: Designed for AI-assisted development with structured issues and Claude Code integration.
---
# Host UK DevOps
The developer workspace orchestrator for Host UK - a federated monorepo containing 18 Laravel packages.
## What's Included
| Component | Purpose |
|-----------|---------|
| `repos.yaml` | Package registry with dependencies |
| `.core/` | Workspace configuration and Claude Code plugin |
| `scripts/` | Cross-platform setup scripts |
| `Makefile` | Setup orchestration |
## Quick Start
```bash
git clone git@github.com:host-uk/core-devops.git && cd core-devops && make setup
```
## Core CLI
The workspace is managed by the `core` CLI:
```bash
core health # Status summary
core work # Commit and push workflow
core issues # GitHub issues across repos
```
## Next Steps
- [Quick Start Guide](/quick-start) - Get up and running
- [Commands Reference](/commands) - All available commands
- [.core/ Configuration](/core-folder) - Workspace configuration

58
doc/package-types.md Normal file
View file

@ -0,0 +1,58 @@
# Package Types
Host UK packages are organised into types based on their purpose.
## Foundation
Base framework with no dependencies.
| Package | Description |
|---------|-------------|
| `core-php` | Event-driven modules, lifecycle management |
## Modules
Infrastructure services that extend the foundation.
| Package | Description | Dependencies |
|---------|-------------|--------------|
| `core-tenant` | Multi-tenancy, workspaces, users | core-php |
| `core-admin` | Admin panel, Livewire, Flux UI | core-php |
| `core-api` | REST API, rate limiting, webhooks | core-php, core-tenant |
| `core-mcp` | Model Context Protocol server | core-php |
| `core-agentic` | AI agent orchestration | core-php, core-tenant, core-mcp |
| `core-commerce` | Billing, subscriptions, Stripe | core-php, core-tenant |
| `core-content` | CMS, pages, blog posts | core-php, core-tenant |
| `core-tools` | Developer utilities | core-php |
| `core-uptelligence` | Server monitoring | core-php, core-tenant |
| `core-developer` | Developer portal, OAuth | core-php, core-tenant, core-api |
## Products
User-facing applications.
| Package | Description | Domain |
|---------|-------------|--------|
| `core-bio` | Link-in-bio pages | bio.host.uk.com |
| `core-social` | Social media scheduling | social.host.uk.com |
| `core-analytics` | Privacy-first analytics | analytics.host.uk.com |
| `core-notify` | Push notifications | notify.host.uk.com |
| `core-trust` | Social proof widgets | trust.host.uk.com |
| `core-support` | Helpdesk, ticketing | - |
## Templates
Starter templates for new projects.
| Package | Description |
|---------|-------------|
| `core-template` | Starter template |
## Meta
Workspace and tooling repos.
| Package | Description |
|---------|-------------|
| `core-devops` | This workspace |
| `core` | Go CLI and framework |

63
doc/quick-start.md Normal file
View file

@ -0,0 +1,63 @@
# Quick Start
Get a complete Host UK development environment in under 5 minutes.
## Prerequisites
- Git
- GitHub CLI (`gh`)
- SSH key configured with GitHub
## Installation
### macOS / Linux
```bash
git clone git@github.com:host-uk/core-devops.git
cd core-devops
make setup
```
### Windows (PowerShell as Admin)
```powershell
git clone git@github.com:host-uk/core-devops.git
cd core-devops
.\scripts\install-deps.ps1
.\scripts\install-core.ps1
core setup
```
## What Happens
`make setup` does three things:
1. **Installs dependencies** - PHP 8.3+, Composer, Node 20+, pnpm, GitHub CLI
2. **Installs the `core` CLI** - Multi-repo management tool
3. **Clones all packages** - Into `packages/` (foundation and modules by default)
## Verify Installation
```bash
core doctor
```
This checks that all required tools are installed and configured.
## Next Steps
```bash
# See workspace status
core health
# Run tests in the active package
core php test
# Work on a specific package
cd packages/core-php
composer test
```
## Troubleshooting
See the [Troubleshooting Guide](/troubleshooting) for common issues.

78
doc/repos-yaml.md Normal file
View file

@ -0,0 +1,78 @@
# repos.yaml
The package registry defining all repositories in the workspace.
## Format
```yaml
version: 1
org: host-uk
base_path: ./packages
repos:
core-php:
type: foundation
description: Core PHP framework
docs: true
ci: github-actions
core-tenant:
type: module
depends_on: [core-php]
description: Multi-tenancy, workspaces
defaults:
ci: github-actions
license: EUPL-1.2
branch: main
```
## Fields
### Repository Fields
| Field | Type | Description |
|-------|------|-------------|
| `type` | string | Package type (see below) |
| `depends_on` | array | Dependencies on other packages |
| `description` | string | Short description |
| `docs` | boolean | Has documentation |
| `ci` | string | CI system (github-actions) |
| `domain` | string | Production domain (products only) |
| `clone` | boolean | Whether to clone (default: true) |
### Package Types
| Type | Purpose | Examples |
|------|---------|----------|
| `foundation` | Base framework, no dependencies | core-php |
| `module` | Infrastructure services | core-tenant, core-admin |
| `product` | User-facing applications | core-bio, core-social |
| `template` | Starter templates | core-template |
| `meta` | Workspace repos | core-devops |
## Using with CLI
```bash
# Clone specific types
core setup --only foundation,module
# Show what depends on a package
core impact core-php
```
## Dependency Graph
The `depends_on` field creates a dependency graph:
```
core-php (foundation)
├── core-tenant
├── core-admin
├── core-api
│ └── core-developer
└── core-mcp
└── core-agentic
```
Products depend on both `core-php` and `core-tenant`.

93
doc/troubleshooting.md Normal file
View file

@ -0,0 +1,93 @@
# Troubleshooting
Common issues and solutions.
## Installation Issues
### "core: command not found"
The Core CLI isn't installed or not in PATH.
```bash
make install-core
```
Or manually:
```bash
./scripts/install-core.sh
```
### "gh: command not found"
Install GitHub CLI:
```bash
# macOS
brew install gh
# Then authenticate
gh auth login -h github.com -p https -s workflow,repo,read:org,read:project,project
```
### Clone failures
Check your SSH keys:
```bash
ssh -T git@github.com
```
If using HTTPS:
```bash
gh auth setup-git
```
## GitHub Issues
### "refusing to allow an OAuth App to create or update workflow"
Missing `workflow` scope:
```bash
gh auth refresh -h github.com -s workflow
```
### "missing required scopes [read:project]"
Missing project scope:
```bash
gh auth refresh -h github.com -s read:project,project
```
## Workspace Issues
### Tests failing in wrong package
Check the active package in `.core/workspace.yaml`:
```yaml
active: core-php # Should match the package you're testing
```
### Packages not found
Run setup to clone packages:
```bash
core setup
```
Or clone specific types:
```bash
core setup --only foundation,module
```
## Getting Help
1. Run `core doctor` to check environment
2. Check GitHub issues: https://github.com/host-uk/core-devops/issues
3. Ask in Discord: https://discord.gg/host-uk

15
package.json Normal file
View file

@ -0,0 +1,15 @@
{
"name": "@host-uk/devops-docs",
"version": "1.0.0",
"private": true,
"type": "module",
"scripts": {
"docs:dev": "vitepress dev",
"docs:build": "vitepress build",
"docs:preview": "vitepress preview"
},
"devDependencies": {
"vitepress": "^1.5.0",
"vue": "^3.5.0"
}
}