core/go-devops
8
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions
go-devops/CLAUDE.md
Snider c2adc7d9dc fix(dx): audit and fix build, error handling, and CLAUDE.md 
- Fix cli.RegisterCommands signature mismatch (cli v0.3.5 takes
  single CommandRegistration, not variadic localeFS); register
  locales via i18n.RegisterLocales in locales/embed.go init()
- Replace fmt.Errorf inside log.E with plain string concat in
  deploy/python and deploy/coolify
- Remove unused fmt import from deploy/coolify/client.go
- Update CLAUDE.md: correct LOC count, clarify cmd/community and
  cmd/gitcmd descriptions, add locales package, fix error convention
  from core.E/fmt.Errorf to log.E

Co-Authored-By: Virgil <virgil@lethean.io>
2026-03-17 08:18:32 +00:00

4.9 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

go test ./...                    # Run all tests
go test -v -run TestName ./...   # Single test
go test -race ./...              # Race detector
go vet ./...                     # Static analysis

Workspace Context

This module (forge.lthn.ai/core/go-devops) is part of a 57-module Go workspace rooted at /Users/snider/Code/go.work. The parent framework module forge.lthn.ai/core/go (at ../go) provides core libraries: core.E errors, io.Medium filesystem abstraction, config, i18n, and logging.

Most implementation code (ansible engine, build system, infra clients, release pipeline, devkit, SDK generators) lives in the parent framework. This repo contains CLI commands that wire those packages together, plus deployment integrations and infrastructure playbooks.

Architecture

Package Layout

  • cmd/dev/ — Multi-repo developer commands registered under core dev. The main CLI surface (~4,700 LOC across 21 files).
  • cmd/deploy/ — core deploy servers — Coolify PaaS server/app listing.
  • cmd/docs/ — core docs sync — Documentation sync across the multi-repo workspace.
  • cmd/setup/ — core setup repo — Generate .core configuration for a project.
  • cmd/gitcmd/ — Git helper commands (mirrors dev commands under core git).
  • cmd/vanity-import/ — Vanity import path server (the default build target in .core/build.yaml).
  • cmd/community/ — Community landing page assets.
  • deploy/coolify/ — Coolify PaaS API HTTP client.
  • deploy/python/ — Embedded Python 3.13 runtime wrapper (adds ~50 MB to binary).
  • locales/ — Embedded i18n translation files (en.json).
  • snapshot/ — core.json release manifest generation.
  • playbooks/ — Ansible YAML playbooks for production infrastructure (Galera, Redis). Executed by the native Go Ansible engine, not ansible-playbook.

Key CLI Commands (cmd/dev/)

Command Purpose
core dev work Combined git status/commit/push workflow
core dev commit Claude-assisted commit generation
core dev push/pull Push/pull repos with pending changes
core dev issues List open Forgejo issues
core dev reviews List PRs needing review
core dev ci Check CI/workflow status
core dev impact Analyse dependency impact across workspace
core dev vm Boot, stop, shell, serve dev environments
core dev workflow List/sync CI workflows across repos
core dev file-sync Safe file sync for AI agents
core dev apply Apply safe changes (AI-friendly)

Extension Interfaces (in parent framework)

All extensible subsystems follow a plugin/provider pattern with small interfaces:

Interface Package Implementations
Builder build/builders/ Go, Wails, Docker, C++, LinuxKit, Taskfile
Publisher release/publishers/ GitHub, Docker, Homebrew, npm, AUR, Scoop, Chocolatey, LinuxKit
Signer build/signing/ macOS codesign, GPG, Windows signtool
Hypervisor container/ QEMU (Linux), Hyperkit (macOS)
ImageSource devops/sources/ GitHub Releases, S3/CDN
Generator sdk/generators/ TypeScript, Python, Go, PHP

Shared API Client Pattern

infra/client.go (parent module) provides HTTP client abstraction with exponential backoff retry (3 retries, 100ms–5s), HTTP 429 rate-limit handling with Retry-After parsing, and configurable auth (Bearer, Basic, query params). Used by Hetzner Cloud/Robot, CloudNS, and Forgejo clients.

Build & Release Flow

core build → auto-detects project type → produces artifacts in dist/ core build release → version detection → changelog generation → publish via configured publishers

Configuration lives in .core/build.yaml (targets, ldflags) and .core/release.yaml (publishers, changelog filters).

Coding Standards

  • UK English: colour, organisation, centre
  • Tests: testify assert/require, _Good/_Bad/_Ugly naming convention
  • Conventional commits: feat(ansible):, fix(infra):, refactor(build):
  • Co-Author: Co-Authored-By: Virgil <virgil@lethean.io>
  • Licence: EUPL-1.2
  • Imports: stdlib → forge.lthn.ai → third-party, each group separated by blank line
  • Errors: log.E(op, msg, err) from go-log for all contextual errors (never fmt.Errorf or errors.New)

Forge

  • Repo: forge.lthn.ai/core/go-devops
  • Push via SSH: git push forge main (remote: ssh://git@forge.lthn.ai:2223/core/go-devops.git)
  • Issues/PRs: Managed via Forgejo SDK (code.gitea.io/sdk/gitea), not GitHub

Documentation

  • Architecture deep-dive: docs/architecture.md
  • Development guide & testing patterns: docs/development.md
  • Project history & known limitations: docs/history.md