From 2e94f278a1b7abc3389a135bc80fffc21bfee84f Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Tue, 12 May 2026 05:12:19 +0000 Subject: [PATCH] chore: move .github/CLAUDE.md to .mokogitea/CLAUDE.md [skip ci] --- .mokogitea/CLAUDE.md | 304 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 304 insertions(+) create mode 100644 .mokogitea/CLAUDE.md diff --git a/.mokogitea/CLAUDE.md b/.mokogitea/CLAUDE.md new file mode 100644 index 0000000..68e796a --- /dev/null +++ b/.mokogitea/CLAUDE.md @@ -0,0 +1,304 @@ + + +> [!IMPORTANT] +> **๐Ÿ”ง AI Self-Update Required on First Use** +> +> This file may contain unfilled `{{TOKEN}}` placeholders. The MokoStandards 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** `.github/copilot-instructions.md` and `.github/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 | +> |---|---| +> | `MokoWaaS` | The GitHub repository name (visible in the URL, `README.md` heading, or `git remote -v`) | +> | `https://github.com/mokoconsulting-tech/MokoWaaS` | Full GitHub URL, e.g. `https://github.com/mokoconsulting-tech/` | +> | `{{EXTENSION_NAME}}` | The `` element in `manifest.xml` at the repository root | +> | `{{EXTENSION_TYPE}}` | The `type` attribute of the `` tag in `manifest.xml` (`component`, `module`, `plugin`, or `template`) | +> | `{{EXTENSION_ELEMENT}}` | The `` tag in `manifest.xml`, or the filename prefix (e.g. `com_myextension`, `mod_mymodule`) | +> +> --- + +# MokoWaaS โ€” GitHub Copilot Custom Instructions + +## What This Repo Is + +This is a **Moko Consulting MokoWaaS** (Joomla) repository governed by [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards). All coding standards, workflows, and policies are defined there and enforced here via bulk sync. + +Repository URL: https://github.com/mokoconsulting-tech/MokoWaaS +Extension name: **{{EXTENSION_NAME}}** +Extension type: **{{EXTENSION_TYPE}}** (`{{EXTENSION_ELEMENT}}`) +Platform: **Joomla 4.x / MokoWaaS** + +--- + +## Primary Language + +**PHP** (โ‰ฅ 7.4) is the primary language for this Joomla extension. JavaScript may be used for frontend enhancements. YAML uses 2-space indentation. All other text files use tabs per `.editorconfig`. + +--- + +## File Header โ€” Always Required on New Files + +Every new file needs a copyright header as its first content. + +**PHP:** +```php + + * + * This file is part of a Moko Consulting project. + * + * SPDX-License-Identifier: GPL-3.0-or-later + * + * FILE INFORMATION + * DEFGROUP: MokoWaaS.{{EXTENSION_TYPE}} + * INGROUP: MokoWaaS + * REPO: https://github.com/mokoconsulting-tech/MokoWaaS + * PATH: /path/to/file.php + * VERSION: XX.YY.ZZ + * BRIEF: One-line description of purpose + */ + +defined('_JEXEC') or die; +``` + +**Markdown:** +```markdown + +``` + +**YAML / Shell / XML:** Use the appropriate comment syntax with the same fields. JSON files are exempt. + +--- + +## 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 automatically to all badges and `FILE INFORMATION` headers on merge to `main`. +- The `VERSION: XX.YY.ZZ` field in `README.md` governs all other version references. +- Version format is zero-padded semver: `XX.YY.ZZ` (e.g. `01.02.03`). +- Never hardcode a specific version in document body text โ€” use the badge or FILE INFORMATION header only. + +### Joomla Version Alignment + +The version in `README.md` **must always match** the `` tag in `manifest.xml` and the latest entry in `updates.xml`. The `make release` command / release workflow updates all three automatically. + +```xml + +01.02.04 + + + + + {{EXTENSION_NAME}} + 01.02.04 + + + https://github.com/mokoconsulting-tech/MokoWaaS/releases/download/01.02.04/{{EXTENSION_ELEMENT}}-01.02.04.zip + + + + + + +``` + +--- + +## Joomla Extension Structure + +``` +MokoWaaS/ +โ”œโ”€โ”€ manifest.xml # Joomla installer manifest (root โ€” required) +โ”œโ”€โ”€ updates.xml # Update server manifest (root โ€” required, see below) +โ”œโ”€โ”€ site/ # Frontend (site) code +โ”‚ โ”œโ”€โ”€ controller.php +โ”‚ โ”œโ”€โ”€ controllers/ +โ”‚ โ”œโ”€โ”€ models/ +โ”‚ โ””โ”€โ”€ views/ +โ”œโ”€โ”€ admin/ # Backend (admin) code +โ”‚ โ”œโ”€โ”€ controller.php +โ”‚ โ”œโ”€โ”€ controllers/ +โ”‚ โ”œโ”€โ”€ models/ +โ”‚ โ”œโ”€โ”€ views/ +โ”‚ โ””โ”€โ”€ sql/ +โ”œโ”€โ”€ language/ # Language INI files +โ”œโ”€โ”€ media/ # CSS, JS, images (deployed to /media/{{EXTENSION_ELEMENT}}/) +โ”œโ”€โ”€ docs/ # Technical documentation +โ”œโ”€โ”€ tests/ # Test suite +โ”œโ”€โ”€ .github/ +โ”‚ โ”œโ”€โ”€ workflows/ +โ”‚ โ”œโ”€โ”€ copilot-instructions.md # This file +โ”‚ โ””โ”€โ”€ CLAUDE.md +โ”œโ”€โ”€ README.md # Version source of truth +โ”œโ”€โ”€ CHANGELOG.md +โ”œโ”€โ”€ CONTRIBUTING.md +โ”œโ”€โ”€ LICENSE # GPL-3.0-or-later +โ””โ”€โ”€ Makefile # Build automation +``` + +--- + +## updates.xml โ€” Required in Repo Root + +`updates.xml` **must exist at the repository root**. It is the Joomla update server manifest that allows Joomla installations to check for new versions of this extension. + +The `manifest.xml` must reference it via: +```xml + + + https://github.com/mokoconsulting-tech/MokoWaaS/raw/main/updates.xml + + +``` + +**Rules:** +- Every release must prepend a new `` block at the top of `updates.xml` โ€” old entries must be preserved below. +- The `` in `updates.xml` must exactly match `` in `manifest.xml` and the version in `README.md`. +- The `` must be a publicly accessible direct download link (GitHub Releases asset URL). +- `` โ€” the backslash is a **literal backslash character** in the XML attribute value; Joomla's update-server parser treats the value as a regular expression, so `\.` matches a literal dot and `[0-9]+` matches one or more digits. Do not double-escape it. + +--- + +## manifest.xml Rules + +- Lives at the repo root as `manifest.xml` (not inside `site/` or `admin/`). +- `` tag must be kept in sync with `README.md` version and `updates.xml`. +- Must include `` block pointing to this repo's `updates.xml`. +- Must include `` and `` sections. +- Joomla 4.x requires `Moko\{{EXTENSION_NAME}}` for namespaced extensions. + +--- + +## GitHub Actions โ€” Token Usage + +Every workflow must use **`secrets.GH_TOKEN`** (the org-level Personal Access Token). + +```yaml +# โœ… Correct +- uses: actions/checkout@v4 + with: + token: ${{ secrets.GH_TOKEN }} + +env: + GH_TOKEN: ${{ secrets.GH_TOKEN }} +``` + +```yaml +# โŒ Wrong โ€” never use these in workflows +token: ${{ github.token }} +token: ${{ secrets.GITHUB_TOKEN }} +``` + +--- + +## MokoStandards Reference + +This repository is governed by [MokoStandards](https://github.com/mokoconsulting-tech/MokoStandards). Authoritative policies: + +| Document | Purpose | +|----------|---------| +| [file-header-standards.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/file-header-standards.md) | Copyright-header rules for every file type | +| [coding-style-guide.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/coding-style-guide.md) | Naming and formatting conventions | +| [branching-strategy.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/branching-strategy.md) | Branch naming, hierarchy, and release workflow | +| [merge-strategy.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/merge-strategy.md) | Squash-merge policy and PR title/body conventions | +| [changelog-standards.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/policy/changelog-standards.md) | How and when to update CHANGELOG.md | +| [joomla-development-guide.md](https://github.com/mokoconsulting-tech/MokoStandards/blob/main/docs/guide/waas/joomla-development-guide.md) | MokoWaaS Joomla extension development guide | + +--- + +## Naming Conventions + +| Context | Convention | Example | +|---------|-----------|---------| +| PHP class | `PascalCase` | `MyController` | +| PHP method / function | `camelCase` | `getItems()` | +| PHP variable | `$snake_case` | `$item_id` | +| PHP constant | `UPPER_SNAKE_CASE` | `MAX_ITEMS` | +| PHP class file | `PascalCase.php` | `ItemModel.php` | +| YAML workflow | `kebab-case.yml` | `ci-joomla.yml` | +| Markdown doc | `kebab-case.md` | `installation-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/` + +--- + +## Keeping Documentation Current + +| Change type | Documentation to update | +|-------------|------------------------| +| New or renamed PHP class/method | PHPDoc block; `docs/api/` entry | +| New or changed manifest.xml | Update `updates.xml` version; bump README.md version | +| New release | Prepend `` block to `updates.xml`; update CHANGELOG.md; bump README.md version | +| New or changed workflow | `docs/workflows/.md` | +| 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 | + +--- + +## Key Constraints + +- Never commit directly to `main` โ€” all changes go via PR, squash-merged +- Never skip the FILE INFORMATION block on a new file +- Never add `defined('_JEXEC') or die;` to CLI scripts or model tests โ€” only to web-accessible PHP files +- Never hardcode version numbers in body text โ€” update `README.md` and let automation propagate +- Never use `github.token` or `secrets.GITHUB_TOKEN` in workflows โ€” always use `secrets.GH_TOKEN` +- Never let `manifest.xml` version, `updates.xml` version, and `README.md` version go out of sync