diff --git a/.mokogitea/CLAUDE.md b/.mokogitea/CLAUDE.md index ea146a19..925ae5db 100644 --- a/.mokogitea/CLAUDE.md +++ b/.mokogitea/CLAUDE.md @@ -1,316 +1,82 @@ - +| 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/` | -> | `{{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`) | -> -> --- +## 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 - - * - * 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 - -``` +### 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 `` 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 - -01.02.04 +## Rules - - - - {{EXTENSION_NAME}} - 01.02.04 - - - https://github.com/mokoconsulting-tech/MokoWaaS/releases/download/01.02.04/{{EXTENSION_ELEMENT}}-01.02.04.zip - - - - - - -``` +- **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 - - - https://git.mokoconsulting.tech/MokoConsulting/MokoWaaS/updates.xml - - -``` - -**License Key (Download Key):** -- MokoGitea's endpoint validates license keys passed as `?dlid=MOKO-XXXX-XXXX-XXXX-XXXX` -- The generated XML includes `` 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 `` response - -**Rules:** -- Do NOT create or commit a static `updates.xml` โ€” MokoGitea generates it from releases -- The `` in release tags must match `` in the manifest and `README.md` -- Release assets (ZIPs) must be attached to git releases โ€” MokoGitea uses them for `` -- `` โ€” 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/`). -- `` 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 | 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/.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