moko-platform/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

moko-platform — Enterprise automation, validation, sync, and governance engine for all Moko Consulting repositories

Field	Value
Language	PHP 8.1+
Default branch	main
License	GPL-3.0-or-later
Version	06.00.00
Wiki	moko-platform Wiki

Common Commands

composer install                         # Install PHP dependencies
php bin/moko health --path .             # Run repo health check
php bin/moko check:syntax --path .       # PHP syntax check
php bin/moko drift --org MokoConsulting  # Scan for standards drift
php bin/moko dashboard --token $TOKEN -o dashboard.html  # Generate client dashboard

# Code quality
php vendor/bin/phpcs --standard=phpcs.xml -n lib/ validate/ automation/ cli/
php vendor/bin/phpcbf --standard=phpcs.xml lib/ validate/ automation/ cli/
php vendor/bin/phpstan analyse -c phpstan.neon --memory-limit=512M

# Run all checks
composer check

Architecture

Directory Layout

Directory	Purpose
cli/	32 standalone CLI tools (version, release, build, repo management)
validate/	20 validation scripts (syntax, structure, manifests, drift)
automation/	7 bulk operations (sync, push files, templates, cleanup)
lib/Enterprise/	Core library — CliFramework, ApiClient, adapters, validators
lib/Enterprise/Plugins/	11 platform plugins (Joomla, Dolibarr, Node.js, Python, etc.)
deploy/	SFTP deployment scripts (Joomla, Dolibarr, health checks)
definitions/	Repository structure definitions (HCL format)
templates/	Workflow templates, config templates, docs templates
.mokogitea/workflows/	CI/CD workflows (Gitea Actions)
bin/moko	Unified CLI dispatcher — runs any tool via php bin/moko <command>

CLI Framework

All CLI tools extend MokoEnterprise\CliFramework (defined in lib/Enterprise/CliFramework.php).

Pattern for new tools:

class MyTool extends CliFramework {
    protected function configure(): void {
        $this->setDescription('What this tool does');
        $this->addArgument('--name', 'Description', 'default');
    }
    protected function run(): int {
        $name = $this->getArgument('--name');
        // ... business logic ...
        return 0;
    }
}
$app = new MyTool();
exit($app->execute());

Built-in flags: --help, --verbose, --quiet, --dry-run

Platform Adapters

Git operations are abstracted via GitPlatformAdapter interface:

• MokoGiteaAdapter — for git.mokoconsulting.tech (primary)
• GitHubAdapter — for github.com mirrors

Plugin System

Platform-specific logic lives in lib/Enterprise/Plugins/. Each plugin implements ProjectPluginInterface with methods for health checks, validation, build commands, and config schemas.

Code Quality

Tool	Level	Config
PHPCS	PSR-12 (errors only)	phpcs.xml
PHPStan	Level 2	phpstan.neon

PHPStan runs with --memory-limit=512M due to large codebase. CI enforces PHPCS errors; PHPStan is advisory (continue-on-error).

Rules

• Workflow directory: .mokogitea/ (not .gitea/ or .github/)
• Never commit .claude/, .mcp.json, TODO.md, or *.min.css/*.min.js
• Attribution: use Authored-by: Moko Consulting in commits
• Branch strategy: develop on dev, merge to main for release
• Minification: handled at build time (CI) and runtime (MokoMinifyHelper for Joomla templates)
• Wiki: documentation lives in the Gitea wiki, not in docs/ files
• New CLI tools: extend CliFramework, not CLIApp (legacy)
• After adding a CLI tool: register it in bin/moko COMMAND_MAP