diff --git a/.github/CLAUDE.md b/.github/CLAUDE.md index 3bffc4c..3687a3e 100644 --- a/.github/CLAUDE.md +++ b/.github/CLAUDE.md @@ -6,60 +6,31 @@ This file is part of a Moko Consulting project. SPDX-License-Identifier: GPL-3.0-or-later # FILE INFORMATION -DEFGROUP: MokoStandards.Templates.GitHub -INGROUP: MokoStandards.Templates -REPO: https://git.mokoconsulting.tech/MokoConsulting/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: MokoOnyx, https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx, {{EXTENSION_NAME}}, - {{EXTENSION_TYPE}}, {{EXTENSION_ELEMENT}} +DEFGROUP: MokoOnyx.GitHub +INGROUP: MokoOnyx +REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx +PATH: /.github/CLAUDE.md +VERSION: 01.00.05 +BRIEF: Claude Code custom instructions for MokoOnyx template --> -> [!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 | -> |---|---| -> | `MokoOnyx` | The GitHub repository name (visible in the URL, `README.md` heading, or `git remote -v`) | -> | `https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx` | Full GitHub URL, e.g. `https://git.mokoconsulting.tech/MokoConsulting/` | -> | `{{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`) | -> -> --- - -# MokoOnyx โ€” GitHub Copilot Custom Instructions +# MokoOnyx โ€” Claude Code Instructions ## What This Repo Is This is a **Moko Consulting MokoWaaS** (Joomla) repository governed by [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards). All coding standards, workflows, and policies are defined there and enforced here via bulk sync. Repository URL: https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx -Extension name: **{{EXTENSION_NAME}}** -Extension type: **{{EXTENSION_TYPE}}** (`{{EXTENSION_ELEMENT}}`) -Platform: **Joomla 4.x / MokoWaaS** +Extension name: **MokoOnyx** +Extension type: **template** (`mokoonyx`) +Platform: **Joomla 5.x / 6.x / MokoWaaS** +Successor to: **MokoCassiopeia** (renamed in v01.00.00) --- ## 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`. +**PHP** (โ‰ฅ 8.1) is the primary language for this Joomla template. JavaScript may be used for frontend enhancements. YAML uses 2-space indentation. All other text files use tabs per `.editorconfig`. --- @@ -77,7 +48,7 @@ Every new file needs a copyright header as its first content. * SPDX-License-Identifier: GPL-3.0-or-later * * FILE INFORMATION - * DEFGROUP: MokoOnyx.{{EXTENSION_TYPE}} + * DEFGROUP: MokoOnyx.Template * INGROUP: MokoOnyx * REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx * PATH: /path/to/file.php @@ -115,139 +86,93 @@ BRIEF: One-line description **`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`. +- **Patch version is auto-bumped by the release workflow** โ€” `release.yml` reads the current version from `README.md`, increments the patch (`XX.YY.ZZ` โ†’ `XX.YY.(ZZ+1)`), updates `README.md`, `templateDetails.xml`, and the matching channel in `updates.xml`, commits, pushes, then builds the ZIP. Manual bumping is no longer required. - 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`). +- Version format is zero-padded semver: `XX.YY.ZZ` (e.g. `01.00.05`). - 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. +The version in `README.md` **must always match** the `` tag in `templateDetails.xml` and the matching channel entry in `updates.xml`. The release workflow updates all three automatically. + +### Multi-Channel updates.xml + +`updates.xml` contains separate `` blocks per stability channel (development, alpha, beta, rc, stable). Each release workflow only modifies its own channel using targeted Python regex replacement โ€” other channels are preserved untouched. Joomla filters by the user's "Minimum Stability" setting. ```xml - -01.02.04 - - - - {{EXTENSION_NAME}} - 01.02.04 - - - https://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/releases/download/01.02.04/{{EXTENSION_ELEMENT}}-01.02.04.zip - - - - - + ...development... + ...alpha... + ...beta... + ...rc... + ...stable... ``` +**Key rules:** +- SHA-256 must be raw hex (no `sha256:` prefix) +- Version format must be `XX.YY.ZZ`, not tag names like `v01` +- Download URLs must point to Gitea (not GitHub) for all pre-release channels +- **Always push updates.xml to main** โ€” Joomla sites read from main, not dev + --- -## Joomla Extension Structure +## MokoCassiopeia Migration (v01.x only) + +MokoOnyx v01.x includes a migration system for MokoCassiopeia users: + +- **`helper/migrate.php`** โ€” runs on first page load via `index.php` bootstrap +- Creates `.migrated` marker file so it only runs once +- Copies template style params from MokoCassiopeia โ†’ MokoOnyx +- Creates matching styles, copies user files, redirects update server +- **Joomla 6 does NOT call `` for templates** โ€” that's why migration runs from `index.php` instead of `script.php` +- The migration script will be **removed in v02.00.00** (see ROADMAP.md) + +--- + +## Template Structure ``` MokoOnyx/ -โ”œโ”€โ”€ 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 +โ”œโ”€โ”€ src/ +โ”‚ โ”œโ”€โ”€ templateDetails.xml # Joomla installer manifest +โ”‚ โ”œโ”€โ”€ script.php # Install/update script (limited in Joomla 6 for templates) +โ”‚ โ”œโ”€โ”€ index.php # Main template file (includes migration bootstrap) +โ”‚ โ”œโ”€โ”€ helper/ +โ”‚ โ”‚ โ”œโ”€โ”€ migrate.php # MokoCassiopeia โ†’ MokoOnyx migration (v01.x) +โ”‚ โ”‚ โ”œโ”€โ”€ favicon.php # Favicon generator +โ”‚ โ”‚ โ””โ”€โ”€ minify.php # Asset minification +โ”‚ โ”œโ”€โ”€ language/ # Language INI files (en-GB, en-US) +โ”‚ โ”œโ”€โ”€ media/ # CSS, JS, images, vendor assets +โ”‚ โ””โ”€โ”€ templates/ # Custom CSS palette starters, theme test +โ”œโ”€โ”€ updates.xml # Update server manifest (root โ€” required) +โ”œโ”€โ”€ .gitea/workflows/ # Gitea Actions workflows +โ”œโ”€โ”€ docs/ # Documentation +โ”œโ”€โ”€ README.md # Version source of truth โ”œโ”€โ”€ CHANGELOG.md -โ”œโ”€โ”€ CONTRIBUTING.md -โ”œโ”€โ”€ LICENSE # GPL-3.0-or-later -โ””โ”€โ”€ Makefile # Build automation +โ””โ”€โ”€ LICENSE ``` --- -## updates.xml โ€” Required in Repo Root +## Gitea Actions โ€” Token Usage -`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://git.mokoconsulting.tech/MokoConsulting/MokoOnyx/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). +Every workflow must use **`secrets.GA_TOKEN`** (the org-level Personal Access Token). ```yaml # โœ… Correct - uses: actions/checkout@v4 with: - token: ${{ secrets.GH_TOKEN }} - -env: - GH_TOKEN: ${{ secrets.GH_TOKEN }} + token: ${{ secrets.GA_TOKEN }} ``` ```yaml -# โŒ Wrong โ€” never use these in workflows +# โŒ Wrong token: ${{ github.token }} token: ${{ secrets.GITHUB_TOKEN }} ``` ---- - -## MokoStandards Reference - -This repository is governed by [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards). Authoritative policies: - -| Document | Purpose | -|----------|---------| -| [file-header-standards.md](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards/blob/main/docs/policy/file-header-standards.md) | Copyright-header rules for every file type | -| [coding-style-guide.md](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards/blob/main/docs/policy/coding-style-guide.md) | Naming and formatting conventions | -| [branching-strategy.md](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards/blob/main/docs/policy/branching-strategy.md) | Branch naming, hierarchy, and release workflow | -| [merge-strategy.md](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards/blob/main/docs/policy/merge-strategy.md) | Squash-merge policy and PR title/body conventions | -| [changelog-standards.md](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards/blob/main/docs/policy/changelog-standards.md) | How and when to update CHANGELOG.md | -| [joomla-development-guide.md](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards/blob/main/docs/guide/waas/joomla-development-guide.md) | MokoWaaS Joomla extension development guide | +Note: Workflows are in `.gitea/workflows/` (not `.github/workflows/`). --- @@ -260,7 +185,7 @@ This repository is governed by [MokoStandards](https://git.mokoconsulting.tech/M | 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` | +| YAML workflow | `kebab-case.yml` | `release.yml` | | Markdown doc | `kebab-case.md` | `installation-guide.md` | --- @@ -286,11 +211,11 @@ Approved prefixes: `dev/` ยท `rc/` ยท `version/` ยท `patch/` ยท `copilot/` ยท `d | 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 templateDetails.xml | Release workflow auto-bumps version across README.md, templateDetails.xml, and updates.xml | +| New release | Trigger `release.yml` โ€” auto-bumps patch, builds ZIP, updates matching channel in `updates.xml` | | 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 | +| **Every release** | **Patch auto-bumped** by `release.yml` โ€” no manual version bump needed | --- @@ -300,5 +225,7 @@ Approved prefixes: `dev/` ยท `rc/` ยท `version/` ยท `patch/` ยท `copilot/` ยท `d - 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 +- Never use `github.token` or `secrets.GITHUB_TOKEN` in workflows โ€” always use `secrets.GA_TOKEN` +- Never let `templateDetails.xml` version, `updates.xml` version, and `README.md` version go out of sync +- Always push `updates.xml` to main after updating on dev (Joomla reads from main) +- Always update documentation when changing MokoStandards-API or MokoStandards repos