diff --git a/templates/mokogitea/CLAUDE.md.template b/templates/mokogitea/CLAUDE.md.template index 35bb5d9..cfc5c54 100644 --- a/templates/mokogitea/CLAUDE.md.template +++ b/templates/mokogitea/CLAUDE.md.template @@ -1,366 +1,34 @@ - - -> [!IMPORTANT] -> **๐Ÿ”ง AI Self-Update Required on First Use** -> -> This file may contain unfilled `{{TOKEN}}` placeholders. The moko-platform bulk-sync system -> replaces them automatically at sync time; if you can still see them, sync has not yet run for -> this repository โ€” or this is a brand-new repo. -> -> **On your very first interaction in this repository, before answering any other question:** -> -> 1. Check whether any `{{TOKEN}}` placeholders remain in this file. -> 2. If they do, locate the values as described in the table below and replace every occurrence -> in **both** `.gitea/copilot-instructions.md` and `.gitea/CLAUDE.md`. -> 3. After replacing all tokens, **delete this entire notice block** (from `> [!IMPORTANT]` -> through the closing `> ---` line) in both files. -> 4. Tell the developer: *"I've self-updated the AI context files with this repository's -> values โ€” all set."* -> -> | Placeholder | Where to find the value | -> |---|---| -> | `{{REPO_NAME}}` | The GitHub repository name (visible in the URL, `README.md` heading, or `git remote -v`) | -> | `{{REPO_URL}}` | Full GitHub URL, e.g. `https://git.mokoconsulting.tech/mokoconsulting-tech/` | -> | `{{REPO_DESCRIPTION}}` | First paragraph of `README.md` body, or the GitHub repo description | -> | `{{PRIMARY_LANGUAGE}}` | The dominant programming language (check file extensions in the repository) | -> | `{{PLATFORM_TYPE}}` | The project type: `PHP library`, `Joomla extension`, `Dolibarr module`, `WaaS site`, etc. โ€” infer from repo structure | -> -> --- - -# What This Repo Is - -**{{REPO_NAME}}** is a Moko Consulting **{{PLATFORM_TYPE}}** repository. +# {{REPO_NAME}} {{REPO_DESCRIPTION}} -Repository URL: {{REPO_URL}} +## Quick Reference -This repository is governed by [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform) โ€” the single source of truth for coding standards, file-header policies, GitHub Actions workflows, and Terraform configuration templates across all Moko Consulting repositories. +| Field | Value | +|---|---| +| **Platform** | {{PLATFORM_TYPE}} | +| **Language** | {{PRIMARY_LANGUAGE}} | +| **Branch** | develop on `dev`, merge to `main` (protected) | +| **Wiki** | [{{REPO_NAME}} Wiki](https://git.mokoconsulting.tech/MokoConsulting/{{REPO_NAME}}/wiki) | ---- - -# Repo Structure - -``` -{{REPO_NAME}}/ -โ”œโ”€โ”€ src/ # Primary source code -โ”œโ”€โ”€ docs/ # Documentation -โ”œโ”€โ”€ tests/ # Test suite -โ”œโ”€โ”€ .gitea/ -โ”‚ โ”œโ”€โ”€ workflows/ # CI/CD workflows (synced from moko-platform) -โ”‚ โ”œโ”€โ”€ ISSUE_TEMPLATE/ # Issue templates (synced from moko-platform) -โ”‚ โ”œโ”€โ”€ copilot-instructions.md # GitHub Copilot custom instructions -โ”‚ โ”œโ”€โ”€ CLAUDE.md # This file โ€” Claude AI assistant context -โ”‚ โ””โ”€โ”€ override.tf # Repository-specific health-check overrides -โ”œโ”€โ”€ README.md # Project overview โ€” version source of truth -โ”œโ”€โ”€ CHANGELOG.md # Version history -โ”œโ”€โ”€ CONTRIBUTING.md # Contribution guidelines -โ””โ”€โ”€ LICENSE # GPL-3.0-or-later -``` - ---- - -# Primary Language - -**{{PRIMARY_LANGUAGE}}** is the primary language for this repository. - -YAML uses 2-space indentation (spaces, not tabs). All other text files use tabs per `.editorconfig`. - ---- - -# Composer Package (PHP repositories) - -This repository requires the moko-platform enterprise library. The package is installed from the private GitHub VCS source. - -`composer.json` must contain: - -```json -{ - "repositories": [ - { - "type": "vcs", - "url": "https://git.mokoconsulting.tech/MokoConsulting/moko-platform" - } - ], - "require": { - "mokoconsulting/mokostandards": "^4.0" - } -} -``` - -Install or update with: +## Commands ```bash -composer install # first time -composer update mokoconsulting/mokostandards # upgrade +make build # Build the project +make lint # Run linters +make validate # Validate structure +make release # Full release pipeline +make clean # Clean build artifacts ``` ---- +## Architecture -# PHP Script Pattern + -All PHP scripts must extend `MokoStandards\Enterprise\CliFramework` โ€” **never** use a standalone class or the legacy `CliBase`. +## Rules -```php -#!/usr/bin/env php - - * - * This file is part of a Moko Consulting project. - * - * SPDX-License-Identifier: GPL-3.0-or-later - * - * FILE INFORMATION - * DEFGROUP: {{REPO_NAME}}.Scripts - * INGROUP: {{REPO_NAME}} - * REPO: {{REPO_URL}} - * PATH: /api/my_script.php - * VERSION: XX.YY.ZZ - * BRIEF: One-line description of what this script does - */ - -declare(strict_types=1); - -require_once __DIR__ . '/vendor/autoload.php'; - -use MokoStandards\Enterprise\CliFramework; - -class MyScript extends CliFramework -{ - protected function configure(): void - { - $this->setDescription('One-line description of what this script does'); - $this->addArgument('--path', 'Repository root path', '.'); - $this->addArgument('--dry-run', 'Preview changes without writing', false); - } - - protected function run(): int - { - $path = $this->getArgument('--path'); - $dryRun = (bool) $this->getArgument('--dry-run'); - - // implementation โ€ฆ - $this->log('INFO', "Processing: {$path}"); - - return 0; - } -} - -$script = new MyScript('my_script', 'One-line description of what this script does'); -exit($script->execute()); -``` - -**CliFramework interface summary:** - -| Member | Purpose | -|--------|---------| -| `configure(): void` | Abstract โ€” register arguments with `addArgument()` | -| `run(): int` | Abstract โ€” main script logic; return the exit code | -| `initialize(): void` | Optional hook โ€” runs after arg-parse, before `run()` | -| `execute(array $argv = []): int` | **Public entry point** โ€” call this at the bottom; it calls `configure()`, parses argv, then calls `run()` | -| `addArgument(string $name, string $desc, mixed $default)` | Register a CLI argument | -| `getArgument(string $name): mixed` | Read a parsed or default argument value | -| `log(string $level, string $message)` | Structured log โ€” levels: INFO SUCCESS WARNING ERROR DEBUG | -| `error(string $message, int $code = 1): never` | Log error and exit | -| `$this->dryRun` | `true` when `--dry-run` is passed | -| `$this->verbose` | `true` when `--verbose` / `-v` is passed | - -**Forbidden patterns in PHP:** - -```php -// โŒ Wrong โ€” legacy base class, not namespaced -class MyScript extends CliBase { โ€ฆ } - -// โŒ Wrong โ€” standalone class with no framework -class MyScript { public function run() { โ€ฆ } } - -// โŒ Wrong โ€” method names and entry-point transposed -protected function execute(): int { โ€ฆ } // should be run() -exit($script->run()); // should be execute() - -// โœ… Correct -class MyScript extends CliFramework { - protected function configure(): void { โ€ฆ } - protected function run(): int { โ€ฆ } -} -$script = new MyScript('name', 'description'); -exit($script->execute()); -``` - ---- - -# Version Management - -**`README.md` is the single source of truth for the repository version.** - -- **Bump the patch version on every PR** โ€” increment `XX.YY.ZZ` (e.g. `01.02.03` โ†’ `01.02.04`) in `README.md` before opening the PR; the `sync-version-on-merge` workflow propagates it to all badges and `FILE INFORMATION` headers automatically on merge to `main`. -- The `VERSION: XX.YY.ZZ` field in the `README.md` `FILE INFORMATION` block governs all other version references. -- Update `README.md` only โ€” the `sync-version-on-merge` workflow propagates it to all badges and `FILE INFORMATION` headers automatically on merge to `main`. -- Version format is zero-padded semver: `XX.YY.ZZ` (e.g. `01.02.03`). -- Never hardcode a version number in body text โ€” use the badge or FILE INFORMATION header only. - ---- - -# File Header Requirements - -Every new file **must** have a copyright header as its first content. JSON files, binary files, generated files, and third-party files are exempt. - -## Minimal header - -**PHP:** -```php - - * - * This file is part of a Moko Consulting project. - * - * SPDX-License-Identifier: GPL-3.0-or-later - * - * FILE INFORMATION - * DEFGROUP: {{REPO_NAME}}.Module - * INGROUP: {{REPO_NAME}} - * REPO: {{REPO_URL}} - * PATH: /src/MyClass.php - * VERSION: XX.YY.ZZ - * BRIEF: One-line description of file purpose - */ - -declare(strict_types=1); -``` - -**Markdown:** -```markdown - -``` - -**YAML / Shell:** Use `#` comments with the same fields. JSON files are exempt. - ---- - -# Coding Standards - -## Naming Conventions - -| Context | Convention | Example | -|---------|-----------|---------| -| PHP class | `PascalCase` | `MyService` | -| PHP method / function | `camelCase` | `getUserData()` | -| PHP variable | `$snake_case` | `$user_id` | -| PHP constant | `UPPER_SNAKE_CASE` | `MAX_RETRIES` | -| PHP class file | `PascalCase.php` | `UserService.php` | -| PHP script file | `snake_case.php` | `check_health.php` | -| YAML workflow | `kebab-case.yml` | `code-quality.yml` | -| Markdown doc | `kebab-case.md` | `coding-style-guide.md` | - -## Commit Messages - -Format: `(): ` โ€” imperative, lower-case subject, no trailing period. - -Valid types: `feat` ยท `fix` ยท `docs` ยท `chore` ยท `ci` ยท `refactor` ยท `style` ยท `test` ยท `perf` ยท `revert` ยท `build` - -## Branch Naming - -Format: `/[/description]` - -Approved prefixes: `dev/` ยท `rc/` ยท `version/` ยท `patch/` ยท `copilot/` ยท `dependabot/` - ---- - -# GitHub Actions โ€” Token Usage - -Every workflow in this repository must use **`secrets.GH_TOKEN`** (the org-level Personal Access Token). - -```yaml -# โœ… Correct โ€” always use GH_TOKEN -- uses: actions/checkout@v4 - with: - token: ${{ secrets.GH_TOKEN }} - -env: - GH_TOKEN: ${{ secrets.GH_TOKEN }} -``` - -```yaml -# โŒ Wrong โ€” never use these -token: ${{ github.token }} -token: ${{ secrets.GITHUB_TOKEN }} -``` - -PHP scripts read the token with: `getenv('GH_TOKEN') ?: getenv('GITHUB_TOKEN')` โ€” `GH_TOKEN` is always preferred; `GITHUB_TOKEN` is a local-dev fallback only. - ---- - -# Keeping Documentation Current - -Whenever you make code changes, update the corresponding documentation in the same commit or PR. Do not leave docs stale. - -| Change type | Documentation to update | -|-------------|------------------------| -| New or renamed public PHP method | PHPDoc block on the method; `docs/api/` index for that class | -| New or changed CLI script argument | Script's own `--help` text; `docs/api/` or equivalent | -| New or changed GitHub Actions workflow | `docs/workflows/.md` | -| New or changed policy | Corresponding file under `docs/policy/` | -| New library class or major feature | `CHANGELOG.md` entry under `Added` | -| Bug fix | `CHANGELOG.md` entry under `Fixed` | -| Breaking change | `CHANGELOG.md` entry under `Changed`; update `CONTRIBUTING.md` if contributor steps change | -| Any modified file | Update the `VERSION` field in that file's `FILE INFORMATION` block | -| **Every PR** | **Bump the patch version** โ€” increment `XX.YY.ZZ` in `README.md`; `sync-version-on-merge` propagates it to all headers and badges on merge | - -If your code change makes any existing doc sentence false or incomplete, fix the doc before closing the PR. - ---- - -# What NOT to Do - -- **Never commit directly to `main`** โ€” all changes go through a PR. -- **Never hardcode version numbers** in body text โ€” update `README.md` and let automation propagate. -- **Never skip the FILE INFORMATION block** on a new source file. -- **Never use bare `catch (\Throwable $e) {}`** โ€” always log or re-throw. -- **Never mix tabs and spaces** within a file โ€” follow `.editorconfig`. -- **Never use `github.token` or `secrets.GITHUB_TOKEN` in workflows** โ€” always use `secrets.GH_TOKEN`. -- **Never extend `CliBase` in PHP scripts** โ€” extend `MokoStandards\Enterprise\CliFramework` instead. -- **Never use `exit($script->run())`** โ€” the correct entry point is `exit($script->execute())`. - ---- - -# Key Policy Documents (moko-platform) - -| Document | Purpose | -|----------|---------| -| [file-header-standards.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/policy/file-header-standards.md) | Copyright-header rules for every file type | -| [coding-style-guide.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/policy/coding-style-guide.md) | Naming and formatting conventions | -| [branching-strategy.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/policy/branching-strategy.md) | Branch naming, hierarchy, and release workflow | -| [merge-strategy.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/policy/merge-strategy.md) | Squash-merge policy and PR conventions | -| [changelog-standards.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/policy/changelog-standards.md) | How and when to update CHANGELOG.md | -| [scripting-standards.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/policy/scripting-standards.md) | PHP script requirements and CliFramework usage | -| [package-installation.md](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/blob/main/docs/guide/package-installation.md) | Installing `mokoconsulting/mokostandards` via Composer | +- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, `*.min.css`/`*.min.js` +- **Attribution**: `Authored-by: Moko Consulting` +- **Workflow directory**: `.mokogitea/` (not `.gitea/` or `.github/`) +- **Wiki**: documentation lives in the Gitea wiki, not `docs/` files +- **Standards**: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)