MokoConsulting/MokoSuiteClient
0
0
Fork 0
Code Issues 112 Pull Requests Releases 5 Wiki Activity

chore: update .mokogitea/CLAUDE.md to reflect current architecture
Generic: Repo Health / Scripts governance (push) Has been cancelled
Details
Generic: Repo Health / Repository health (push) Has been cancelled
Details
Generic: Repo Health / Report Issues (push) Has been cancelled
Details
Generic: Repo Health / Site Health (push) Has been cancelled
Details
Generic: Repo Health / Access control (push) Has been cancelled
Details
Universal: Auto Version Bump / Version Bump (push) Has been cancelled
Details

Browse Source 
Remove outdated branding/identity description, fix source directory
paths, update extension list to include all 17 sub-extensions,
document updates.xml is now in-repo, add Joomla 5/6 event compat note.

Authored-by: Moko Consulting
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jonathan Miller
2026-06-06 09:13:21 -05:00
parent d94909eb91
commit b24c563cc9
1 changed files with 61 additions and 295 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.mokogitea/CLAUDE.md
+61 -295
View File
@@ -1,316 +1,82 @@
<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
# MokoWaaS
This file is part of a Moko Consulting project.
Joomla 5/6 admin tools suite — heartbeat health monitoring, extension management, security firewall, tenant restrictions, and site administration.
SPDX-License-Identifier: GPL-3.0-or-later
## Quick Reference
# FILE INFORMATION
DEFGROUP: MokoStandards.Templates.GitHub
INGROUP: MokoStandards.Templates
REPO: https://github.com/mokoconsulting-tech/MokoStandards
PATH: /templates/github/copilot-instructions.joomla.md.template
VERSION: XX.YY.ZZ
BRIEF: GitHub Copilot custom instructions template for Joomla/MokoWaaS governed repositories
NOTE: Synced to .github/copilot-instructions.md in all Joomla/WaaS repos via bulk sync.
Tokens replaced at sync time: MokoWaaS, https://github.com/mokoconsulting-tech/MokoWaaS, {{EXTENSION_NAME}},
{{EXTENSION_TYPE}}, {{EXTENSION_ELEMENT}}
-->
| Field | Value |
|---|---|
| **Package** | `pkg_mokowaas` |
| **Language** | PHP 8.1+ |
| **Branch** | develop on `dev`, merge to `main` (protected) |
| **Wiki** | [MokoWaaS Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/wiki) |
> [!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/<repo-name>` |
> | `{{EXTENSION_NAME}}` | The `<name>` element in `manifest.xml` at the repository root |
> | `{{EXTENSION_TYPE}}` | The `type` attribute of the `<extension>` tag in `manifest.xml` (`component`, `module`, `plugin`, or `template`) |
> | `{{EXTENSION_ELEMENT}}` | The `<element>` tag in `manifest.xml`, or the filename prefix (e.g. `com_myextension`, `mod_mymodule`) |
>
> ---
## Commands
# 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
<?php
/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
*
* 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;
```bash
composer install # Install PHP dependencies
```
**Markdown:**
```markdown
<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
## Architecture
This file is part of a Moko Consulting project.
Joomla **package** (`pkg_mokowaas`) with 17 sub-extensions:
SPDX-License-Identifier: GPL-3.0-or-later
### Core Plugin (`plg_system_mokowaas`)
- Heartbeat health endpoint (`/?mokowaas=health`) with 16 diagnostic checks
- Grafana provisioning and heartbeat sender
- Site alias / domain management
- Extension cascade (enable/disable coordination)
- Download key preservation across Joomla updates
- Namespace: `Moko\Plugin\System\MokoWaaS`
# FILE INFORMATION
DEFGROUP: MokoWaaS.Documentation
INGROUP: MokoWaaS
REPO: https://github.com/mokoconsulting-tech/MokoWaaS
PATH: /docs/file.md
VERSION: XX.YY.ZZ
BRIEF: One-line description
-->
```
### Feature Plugins
- `plg_system_mokowaas_firewall` — WAF, IP blocklist, security headers, password policy
- `plg_system_mokowaas_tenant` — admin restrictions for non-master users
- `plg_system_mokowaas_devtools` — dev mode, hit reset, version cleanup, download key reset
- `plg_system_mokowaas_offline` — offline mode bypass for legal pages
- `plg_system_mokowaas_monitor` — Grafana heartbeat registration
**YAML / Shell / XML:** Use the appropriate comment syntax with the same fields. JSON files are exempt.
### Component (`com_mokowaas`)
- Admin dashboard with plugin management, WAF charts, extension catalog
- Helpdesk ticketing system
- REST API controllers
---
### Modules
- `mod_mokowaas_cpanel` — admin dashboard widget
- `mod_mokowaas_menu` — admin sidebar menu
- `mod_mokowaas_cache` — status bar cache/temp cleaner
- `mod_mokowaas_categories` — auto-category tree menu
## Version Management
### Task Plugins
- `plg_task_mokowaasdemo` — scheduled demo site reset
- `plg_task_mokowaassync` — scheduled content sync
- `plg_task_mokowaas_tickets` — ticket automation
**`README.md` is the single source of truth for the repository version.**
### Update Server
- **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.
`updates.xml` is stored in the repo root and maintained manually. Points to ZIP assets on Gitea releases.
### Joomla Version Alignment
## Source Directory
The version in `README.md` **must always match** the `<version>` tag in `manifest.xml` and the latest entry in `updates.xml`. The `make release` command / release workflow updates all three automatically.
Source lives in `source/` (not `src/`):
- `source/pkg_mokowaas.xml` — package manifest
- `source/script.php` — install script
- `source/packages/` — all sub-extensions
```xml
<!-- In manifest.xml — must match README.md version -->
<version>01.02.04</version>
## Rules
<!-- In updates.xml — prepend a new <update> block for every release.
Note: the backslash in version="4\.[0-9]+" is a literal backslash character
in the XML attribute value. Joomla's update server treats the value as a
regular expression, so \. matches a literal dot. -->
<updates>
<update>
<name>{{EXTENSION_NAME}}</name>
<version>01.02.04</version>
<downloads>
<downloadurl type="full" format="zip">
https://github.com/mokoconsulting-tech/MokoWaaS/releases/download/01.02.04/{{EXTENSION_ELEMENT}}-01.02.04.zip
</downloadurl>
</downloads>
<targetplatform name="joomla" version="4\.[0-9]+" />
</update>
<!-- … older entries preserved below … -->
</updates>
```
- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, `*.min.css`/`*.min.js`
- **Attribution**: `Authored-by: Moko Consulting`
- **Workflow directory**: `.mokogitea/` (not `.gitea/` or `.github/`)
- **Minification**: handled at build time (CI)
- **Wiki**: documentation lives in the Gitea wiki, not `docs/` files
- **Standards**: [moko-platform](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)
---
## Coding Standards
## Joomla Extension Structure
```
MokoWaaS/
├── manifest.xml # Joomla installer manifest (root — required)
├── (no updates.xml) # Update XML is generated dynamically by MokoGitea
├── 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
```
---
## Update Server — MokoGitea Dynamic Endpoint
`updates.xml` is **NOT** stored in the repo. MokoGitea generates the update XML dynamically from git releases at:
```
https://git.mokoconsulting.tech/{Owner}/{Repo}/updates.xml
```
The package manifest (`pkg_mokowaas.xml`) references it via:
```xml
<updateservers>
<server type="extension" priority="1" name="MokoWaaS Update Server">
https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/updates.xml
</server>
</updateservers>
```
**License Key (Download Key):**
- MokoGitea's endpoint validates license keys passed as `?dlid=MOKO-XXXX-XXXX-XXXX-XXXX`
- The generated XML includes `<downloadkey prefix="dlid=" suffix="" />` to tell Joomla a key is required
- Users enter the download key via Joomla's native **System → Update Sites** interface
- Joomla stores the key in `#__update_sites.extra_query` and appends it to all update/download requests
- Invalid/expired keys receive an empty `<updates></updates>` response
**Rules:**
- Do NOT create or commit a static `updates.xml` — MokoGitea generates it from releases
- The `<version>` in release tags must match `<version>` in the manifest and `README.md`
- Release assets (ZIPs) must be attached to git releases — MokoGitea uses them for `<downloadurl>`
- `<targetplatform name="joomla" version="(5|6)\..*">` — the backslash is a **literal backslash character** in the XML attribute value; Joomla's update-server parser treats the value as a regular expression
---
## manifest.xml Rules
- Lives at the repo root as `manifest.xml` (not inside `site/` or `admin/`).
- `<version>` tag must be kept in sync with `README.md` version and `updates.xml`.
- Must include `<updateservers>` block pointing to this repo's `updates.xml`.
- Must include `<files folder="site">` and `<administration>` sections.
- Joomla 4.x requires `<namespace path="src">Moko\{{EXTENSION_NAME}}</namespace>` 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: `<type>(<scope>): <subject>` — imperative, lower-case subject, no trailing period.
Valid types: `feat` · `fix` · `docs` · `chore` · `ci` · `refactor` · `style` · `test` · `perf` · `revert` · `build`
---
## Branch Naming
Format: `<prefix>/<MAJOR.MINOR.PATCH>[/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 | Bump README.md version |
| New release | Create git release with ZIP asset; update CHANGELOG.md; bump README.md version |
| New or changed workflow | `docs/workflows/<workflow-name>.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 and `README.md` version go out of sync
- Never commit a static `updates.xml` — the update feed is generated dynamically by MokoGitea
- PHP 8.1+ minimum
- Joomla 5/6 DI container pattern: `services/provider.php` → Extension class
- `SubscriberInterface` for event subscription
- Joomla 5/6 dual-compat for events: check `is_object($event)` with `getArgument()` fallback
- SPDX license headers on all PHP files
- `defined('_JEXEC') or die;` on all web-accessible PHP files