diff --git a/.mokogitea/CLAUDE.md b/.mokogitea/CLAUDE.md new file mode 100644 index 00000000..64abe292 --- /dev/null +++ b/.mokogitea/CLAUDE.md @@ -0,0 +1,83 @@ +# MokoJoomCross + +Cross-posting Joomla content to social media, email marketing, and chat platforms with plugin-based services. + +## Quick Reference + +| Field | Value | +|---|---| +| **Package** | `pkg_mokojoomcross` | +| **Language** | PHP 8.1+ | +| **Branch** | develop on `dev`, merge to `main` (protected) | +| **Wiki** | [MokoJoomCross Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomCross/wiki) | + +## Commands + +```bash +make build # Build package ZIP +make lint # Run linters +make validate # Validate structure +make release # Full release pipeline +make clean # Clean build artifacts +composer install # Install PHP dependencies +``` + +## Architecture + +Joomla **package** with core extensions + pluggable service plugins: + +### com_mokojoomcross (Component) +- Admin backend: dashboard, services, post queue, templates, logs +- Joomla 5/6 MVC: Dashboard, Services, Posts, Logs (list/edit each) +- Namespace: `Joomla\Component\MokoJoomCross\Administrator` + +### plg_system_mokojoomcross (System Plugin) +- Hooks `onContentAfterSave` to trigger cross-posting on article publish +- Dispatches to registered service plugins via `mokojoomcross` plugin group + +### plg_content_mokojoomcross (Content Plugin) +- Adds cross-post status badges to articles via `onContentBeforeDisplay` + +### plg_webservices_mokojoomcross (WebServices Plugin) +- REST API endpoints for posts and services + +### Service Plugins (mokojoomcross group) +Each platform is a separate plugin implementing `MokoJoomCrossServiceInterface`: +- `plg_mokojoomcross_facebook` — Facebook/Meta Graph API +- `plg_mokojoomcross_twitter` — X/Twitter API v2 +- `plg_mokojoomcross_linkedin` — LinkedIn Share API +- `plg_mokojoomcross_mastodon` — Mastodon API +- `plg_mokojoomcross_bluesky` — Bluesky AT Protocol +- `plg_mokojoomcross_mailchimp` — Mailchimp Campaigns API +- `plg_mokojoomcross_telegram` — Telegram Bot API +- `plg_mokojoomcross_discord` — Discord Webhooks +- `plg_mokojoomcross_slack` — Slack Incoming Webhooks + +### Database Schema + +- `#__mokojoomcross_services` — service configs (credentials as individual fields, not JSON) +- `#__mokojoomcross_posts` — post queue (status: queued/posting/posted/failed/scheduled) +- `#__mokojoomcross_templates` — message templates per service type +- `#__mokojoomcross_logs` — activity logs with level and context + +## Rules + +- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, `*.min.css`/`*.min.js` +- **Never commit** API keys, tokens, or credentials — these go in Joomla's encrypted params +- **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**: [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) +- **UX**: service credentials as individual form fields, not JSON blobs; dashboard link in toolbar + +## Coding Standards + +- PHP 8.1+ minimum +- Joomla 5/6 DI container pattern: `services/provider.php` → Extension class +- Legacy stub `.php` file required for plugin loader but empty +- `SubscriberInterface` for event subscription (not `on*` method naming) +- `bind() → check() → store()` for Table operations (not `save()`) +- Language file placement: site (no `folder`) vs admin (`folder="administrator"`) +- SPDX license headers on all PHP files +- Service plugins MUST implement `MokoJoomCrossServiceInterface` diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index a8407b3f..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,112 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code when working with this repository. - -## Project Overview - -**MokoJoomCross** -- Cross-posting Joomla content to social media, email marketing, and chat platforms - -| Field | Value | -|---|---| -| **Platform** | joomla | -| **Language** | PHP | -| **Default branch** | main | -| **License** | GPL-3.0-or-later | -| **Wiki** | [MokoJoomCross Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoJoomCross/wiki) | -| **Standards** | [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) | - -## Common Commands - -```bash -make build # Build the project -make lint # Run linters -make validate # Validate structure -make release # Full release pipeline -make minify # Minify CSS/JS assets -make clean # Clean build artifacts -``` - -```bash -composer install # Install PHP dependencies -``` - -## Architecture - -This is a Joomla **package** extension (`pkg_mokojoomcross`) containing sub-extensions: - -### com_mokojoomcross (Component) -- Admin backend for managing services, post queue, templates, and logs -- Joomla 5/6 MVC: Dashboard, Services, Posts, Logs (list/edit each) -- Namespace: `Joomla\Component\MokoJoomCross\Administrator` -- Database tables: `#__mokojoomcross_services`, `#__mokojoomcross_posts`, `#__mokojoomcross_templates`, `#__mokojoomcross_logs` - -### plg_system_mokojoomcross (System Plugin) -- Hooks `onContentAfterSave` to trigger cross-posting when articles are published -- Dispatches to registered service plugins via the `mokojoomcross` plugin group -- Namespace: `Joomla\Plugin\System\MokoJoomCross` - -### plg_content_mokojoomcross (Content Plugin) -- Hooks `onContentBeforeDisplay` to add cross-post status badges to articles -- Namespace: `Joomla\Plugin\Content\MokoJoomCross` - -### plg_webservices_mokojoomcross (WebServices Plugin) -- REST API endpoints for posts and services -- Namespace: `Joomla\Plugin\WebServices\MokoJoomCross` - -### Service Plugins (mokojoomcross group) -Each platform is a separate plugin in the custom `mokojoomcross` plugin group: -- `plg_mokojoomcross_facebook` — Facebook/Meta Graph API -- `plg_mokojoomcross_twitter` — X/Twitter API v2 -- `plg_mokojoomcross_linkedin` — LinkedIn Share API -- `plg_mokojoomcross_mastodon` — Mastodon API -- `plg_mokojoomcross_bluesky` — Bluesky AT Protocol -- `plg_mokojoomcross_mailchimp` — Mailchimp Campaigns API -- `plg_mokojoomcross_telegram` — Telegram Bot API (default @MokoWaaSBot + custom bot) -- `plg_mokojoomcross_discord` — Discord Webhooks -- `plg_mokojoomcross_slack` — Slack Incoming Webhooks - -### Database Schema - -Four tables: - -`#__mokojoomcross_services`: -- `id`, `title`, `alias`, `service_type` (facebook, twitter, etc.) -- `credentials` (JSON encrypted), `params` (JSON) -- `published`, `ordering`, `created`, `modified`, `created_by` - -`#__mokojoomcross_posts`: -- `id`, `article_id` (FK to #__content), `service_id` (FK) -- `status` (queued/posting/posted/failed/scheduled) -- `message`, `platform_post_id`, `platform_response` (JSON) -- `scheduled_at`, `posted_at`, `retry_count` -- `created`, `modified` - -`#__mokojoomcross_templates`: -- `id`, `service_type`, `title`, `template_body` -- `published`, `ordering`, `created`, `modified` - -`#__mokojoomcross_logs`: -- `id`, `post_id` (FK), `service_id` (FK) -- `level` (info/warning/error), `message`, `context` (JSON) -- `created` - -## Rules - -- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, or `*.min.css`/`*.min.js` -- **Never commit** API keys, tokens, or credentials — these go in Joomla's encrypted params -- **Attribution**: use `Authored-by: Moko Consulting` in commits -- **Branch strategy**: develop on `dev`, merge to `main` for release -- **Minification**: handled at build time (CI) -- **Wiki**: documentation lives in the Gitea wiki, not in `docs/` files -- **Standards**: this repo follows [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home) - -## Coding Standards - -- PHP 8.1+ minimum -- Joomla 5/6 DI container pattern: `services/provider.php` → Extension class -- Legacy stub `.php` file required for plugin loader but empty -- `SubscriberInterface` for event subscription (not `on*` method naming) -- `bind() → check() → store()` for Table operations (not `save()`) -- Language file placement: site (no `folder`) vs admin (`folder="administrator"`) -- SPDX license headers on all PHP files -- Service plugins MUST implement `MokoJoomCrossServiceInterface`