From 97aab0fcca019c6f5d44887495e7dbed524434db Mon Sep 17 00:00:00 2001 From: Snider Date: Sat, 31 Jan 2026 20:28:07 +0000 Subject: [PATCH] docs: add VitePress documentation with GitHub Pages deployment - 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 --- .github/workflows/docs.yml | 59 ++++++++++++++++ .vitepress/config.ts | 78 +++++++++++++++++++++ .vitepress/theme/custom.css | 33 +++++++++ .vitepress/theme/index.ts | 21 ++++++ doc/commands.md | 134 ++++++++++++++++++++++++++++++++++++ doc/core-folder.md | 80 +++++++++++++++++++++ doc/index.md | 56 +++++++++++++++ doc/package-types.md | 58 ++++++++++++++++ doc/quick-start.md | 63 +++++++++++++++++ doc/repos-yaml.md | 78 +++++++++++++++++++++ doc/troubleshooting.md | 93 +++++++++++++++++++++++++ package.json | 15 ++++ 12 files changed, 768 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 .vitepress/config.ts create mode 100644 .vitepress/theme/custom.css create mode 100644 .vitepress/theme/index.ts create mode 100644 doc/commands.md create mode 100644 doc/core-folder.md create mode 100644 doc/index.md create mode 100644 doc/package-types.md create mode 100644 doc/quick-start.md create mode 100644 doc/repos-yaml.md create mode 100644 doc/troubleshooting.md create mode 100644 package.json diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..1e5c31e --- /dev/null +++ b/.github/workflows/docs.yml @@ -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 diff --git a/.vitepress/config.ts b/.vitepress/config.ts new file mode 100644 index 0000000..4ab3d46 --- /dev/null +++ b/.vitepress/config.ts @@ -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 + } +}) diff --git a/.vitepress/theme/custom.css b/.vitepress/theme/custom.css new file mode 100644 index 0000000..d72065e --- /dev/null +++ b/.vitepress/theme/custom.css @@ -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; +} diff --git a/.vitepress/theme/index.ts b/.vitepress/theme/index.ts new file mode 100644 index 0000000..d21283c --- /dev/null +++ b/.vitepress/theme/index.ts @@ -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 diff --git a/doc/commands.md b/doc/commands.md new file mode 100644 index 0000000..46e2d37 --- /dev/null +++ b/doc/commands.md @@ -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 +``` diff --git a/doc/core-folder.md b/doc/core-folder.md new file mode 100644 index 0000000..27cd501 --- /dev/null +++ b/doc/core-folder.md @@ -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. diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..fa191a6 --- /dev/null +++ b/doc/index.md @@ -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 diff --git a/doc/package-types.md b/doc/package-types.md new file mode 100644 index 0000000..0a0da93 --- /dev/null +++ b/doc/package-types.md @@ -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 | diff --git a/doc/quick-start.md b/doc/quick-start.md new file mode 100644 index 0000000..d4366a1 --- /dev/null +++ b/doc/quick-start.md @@ -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. diff --git a/doc/repos-yaml.md b/doc/repos-yaml.md new file mode 100644 index 0000000..6eec512 --- /dev/null +++ b/doc/repos-yaml.md @@ -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`. diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md new file mode 100644 index 0000000..24ce010 --- /dev/null +++ b/doc/troubleshooting.md @@ -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 diff --git a/package.json b/package.json new file mode 100644 index 0000000..3c2ae4d --- /dev/null +++ b/package.json @@ -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" + } +}