Add Claude .md and skill
This commit is contained in:
Darren Clarke
parent
1b5f85627c
commit
99b92fe4ce
3 changed files with 319 additions and 0 deletions
197
.claude/skills/zammad-compat/SKILL.md
Normal file
197
.claude/skills/zammad-compat/SKILL.md
Normal file
|
|
@ -0,0 +1,197 @@
|
|||
---
|
||||
name: zammad-compat
|
||||
description: Check upstream Zammad for breaking changes before upgrading the addon
|
||||
disable-model-invocation: true
|
||||
argument-hint: "[target-version]"
|
||||
allowed-tools: Bash(git clone *), Bash(git -C /tmp/zammad-upstream *)
|
||||
---
|
||||
|
||||
# Zammad Upstream Compatibility Check
|
||||
|
||||
Check the upstream zammad/zammad repository for changes that could break or require updates to our Zammad addon (`packages/zammad-addon-link`).
|
||||
|
||||
## Arguments
|
||||
|
||||
- `$ARGUMENTS` - Optional: target Zammad version/tag/branch to compare against (e.g. `6.6.0`, `stable`). If not provided, ask the user what version to compare against. The current version is in `docker/zammad/Dockerfile` as the `ZAMMAD_VERSION` ARG.
|
||||
|
||||
## Setup
|
||||
|
||||
1. Read the current Zammad version from `docker/zammad/Dockerfile` (the `ARG ZAMMAD_VERSION=` line).
|
||||
2. Clone or update the upstream Zammad repository:
|
||||
- If `/tmp/zammad-upstream` does not exist, clone it: `git clone --bare https://github.com/zammad/zammad.git /tmp/zammad-upstream`
|
||||
- If it exists, update it: `git -C /tmp/zammad-upstream fetch --all --tags`
|
||||
3. Determine the version range. The current version is the `ZAMMAD_VERSION` from step 1. The target version is the argument or user-provided version. Both versions should be used as git refs (tags are typically in the format `X.Y.Z`).
|
||||
|
||||
## Checks to Perform
|
||||
|
||||
Run ALL of these checks and compile results into a single report.
|
||||
|
||||
### 1. Replaced Stock Files
|
||||
|
||||
These are stock Zammad files that our addon REPLACES with modified copies. Changes upstream mean we need to port those changes into our modified versions.
|
||||
|
||||
For each file below, diff the upstream version between the current and target version. Report any changes found.
|
||||
|
||||
**Vue/TypeScript (Desktop UI):**
|
||||
- `app/frontend/apps/desktop/pages/ticket/components/TicketDetailView/ArticleReply.vue`
|
||||
- `app/frontend/apps/desktop/pages/personal-setting/views/PersonalSettingNotifications.vue`
|
||||
- `app/frontend/apps/desktop/components/Form/fields/FieldNotifications/FieldNotificationsInput.vue`
|
||||
- `app/frontend/apps/desktop/components/Form/fields/FieldNotifications/types.ts`
|
||||
|
||||
**CoffeeScript (Legacy UI):**
|
||||
- `app/assets/javascripts/app/controllers/_profile/notification.coffee`
|
||||
- `app/assets/javascripts/app/controllers/_ui_element/notification_matrix.coffee`
|
||||
- `app/assets/javascripts/app/lib/mixins/ticket_notification_matrix.coffee`
|
||||
- `app/assets/javascripts/app/views/generic/notification_matrix.jst.eco`
|
||||
- `app/assets/javascripts/app/views/profile/notification.jst.eco`
|
||||
|
||||
Command pattern for each file:
|
||||
```bash
|
||||
git -C /tmp/zammad-upstream diff <current-version> <target-version> -- <file-path>
|
||||
```
|
||||
|
||||
If a file does not exist at either version, note that (it may have been added, removed, or renamed).
|
||||
|
||||
### 2. Monkey-Patched Files
|
||||
|
||||
These are files our addon patches at runtime via Ruby `prepend`, `include`, or `after_initialize` hooks. Changes to these files could break our patches.
|
||||
|
||||
**Search Backend (OpenSearch compatibility patch):**
|
||||
- `lib/search_index_backend.rb` - We prepend `SearchIndexBackendOpenSearchPatch` to override `_mapping_item_type_es`. Check if this method signature or the `'flattened'` string usage has changed.
|
||||
|
||||
**Core Models (callback injection targets):**
|
||||
- `app/models/ticket/article.rb` - We inject `after_create` callbacks via `include` for Signal and WhatsApp message delivery. Check for changes to the callback chain, model structure, or the `Sender`/`Type` lookup patterns.
|
||||
- `app/models/link.rb` - We inject an `after_create` callback for Signal group setup on ticket split. Check for structural changes.
|
||||
|
||||
**Transaction System:**
|
||||
- `app/models/transaction/` directory - We register `Transaction::SignalNotification` as backend `0105_signal_notification`. Check if the transaction backend system has been refactored.
|
||||
|
||||
**Icons:**
|
||||
- `public/assets/images/icons.svg` - Our initializers append SVG icons at boot time. Check if the SVG structure or the icon injection mechanism has changed.
|
||||
|
||||
Command pattern:
|
||||
```bash
|
||||
git -C /tmp/zammad-upstream diff <current-version> <target-version> -- <file-path>
|
||||
```
|
||||
|
||||
For the search backend specifically, also check if `_mapping_item_type_es` still exists and still returns `'flattened'`:
|
||||
```bash
|
||||
git -C /tmp/zammad-upstream show <target-version>:lib/search_index_backend.rb | grep -n -A5 '_mapping_item_type_es\|flattened'
|
||||
```
|
||||
|
||||
### 3. API Surface Dependencies
|
||||
|
||||
These are Zammad APIs/interfaces/mixins our addon relies on. Changes could cause runtime failures.
|
||||
|
||||
**Channel Driver Interface:**
|
||||
- `app/models/channel/driver/` - Check if the driver base class or interface expectations have changed (methods: `fetchable?`, `disconnect`, `deliver`, `streamable?`).
|
||||
|
||||
**Controller Concerns:**
|
||||
- `app/controllers/concerns/creates_ticket_articles.rb` - Used by our webhook controllers. Check for interface changes.
|
||||
|
||||
**Ticket Article Types & Senders:**
|
||||
- `app/models/ticket/article/type.rb` and `app/models/ticket/article/sender.rb` - We look up types by name (`'signal message'`, `'whatsapp message'`). Check for changes in how types are registered or looked up.
|
||||
|
||||
**Authentication/Authorization:**
|
||||
- `app/policies/` directory structure - We create policies matching `controllers/` names. Check if the policy naming convention or base class has changed.
|
||||
|
||||
**Package System:**
|
||||
- `lib/package.rb` or the package install/uninstall API - We use `Package.install(file:)` and `Package.uninstall(name:, version:)` in setup.rb.
|
||||
|
||||
**Scheduler/Job System:**
|
||||
- `app/jobs/` base class patterns - Our jobs inherit from ApplicationJob. Check for changes.
|
||||
|
||||
Command pattern:
|
||||
```bash
|
||||
git -C /tmp/zammad-upstream diff --stat <current-version> <target-version> -- <path>
|
||||
git -C /tmp/zammad-upstream diff <current-version> <target-version> -- <specific-file>
|
||||
```
|
||||
|
||||
### 4. Path Collision Detection
|
||||
|
||||
Check if the target Zammad version has added any NEW files at paths that collide with our addon files. Our addon installs files at these paths:
|
||||
|
||||
**Controllers:** `app/controllers/channels_cdr_signal_controller.rb`, `channels_cdr_voice_controller.rb`, `channels_cdr_whatsapp_controller.rb`, `cdr_signal_channels_controller.rb`, `cdr_ticket_article_types_controller.rb`, `formstack_controller.rb`, `opensearch_controller.rb`
|
||||
|
||||
**Models:** `app/models/channel/driver/cdr_signal.rb`, `cdr_whatsapp.rb`, `app/models/ticket/article/enqueue_communicate_cdr_signal_job.rb`, `enqueue_communicate_cdr_whatsapp_job.rb`, `app/models/link/setup_split_signal_group.rb`, `app/models/transaction/signal_notification.rb`
|
||||
|
||||
**Jobs:** `app/jobs/communicate_cdr_signal_job.rb`, `communicate_cdr_whatsapp_job.rb`, `signal_notification_job.rb`, `create_ticket_from_form_job.rb`
|
||||
|
||||
**Libraries:** `lib/cdr_signal.rb`, `cdr_signal_api.rb`, `cdr_signal_poller.rb`, `cdr_whatsapp.rb`, `cdr_whatsapp_api.rb`, `signal_notification_sender.rb`
|
||||
|
||||
**Routes:** `config/routes/cdr_signal_channels.rb`, `channel_cdr_signal.rb`, `channel_cdr_voice.rb`, `channel_cdr_whatsapp.rb`, `cdr_ticket_article_types.rb`, `formstack.rb`, `opensearch.rb`
|
||||
|
||||
**Frontend Plugins:** `app/frontend/shared/entities/ticket-article/action/plugins/cdr_signal.ts`, `cdr_whatsapp.ts`, `app/frontend/apps/desktop/pages/ticket/components/TicketDetailView/article-type/plugins/signalMessage.ts`, `whatsappMessage.ts`
|
||||
|
||||
Check if any of these paths exist in the target version:
|
||||
```bash
|
||||
for path in <list-of-paths>; do
|
||||
git -C /tmp/zammad-upstream show <target-version>:$path 2>/dev/null && echo "COLLISION: $path exists upstream"
|
||||
done
|
||||
```
|
||||
|
||||
### 5. Dockerfile Patch Targets
|
||||
|
||||
Check files that are patched at Docker build time via `sed`:
|
||||
|
||||
- `lib/search_index_backend.rb` - `sed` replaces `'flattened'` with `'flat_object'`. Verify the string still exists in the target version.
|
||||
- `contrib/nginx/zammad.conf` - Structure modified for embedded mode. Check for format changes.
|
||||
- `docker-entrypoint.sh` - We inject addon install commands after the `# es config` comment. Verify this comment/anchor still exists.
|
||||
|
||||
Check the upstream Docker entrypoint:
|
||||
```bash
|
||||
git -C /tmp/zammad-upstream show <target-version>:contrib/docker/docker-entrypoint.sh 2>/dev/null | grep -n 'es config' || echo "Anchor comment not found - check entrypoint structure"
|
||||
```
|
||||
|
||||
Also check the Zammad Docker Compose repo if relevant (the base image may come from `zammad/zammad-docker-compose`).
|
||||
|
||||
### 6. Database Schema Conflicts
|
||||
|
||||
Check if the target Zammad version adds any columns or tables that could conflict with our migrations:
|
||||
- Column names: `whatsapp_uid`, `signal_uid`, `signal_username` on the users table
|
||||
- Setting names containing: `signal_notification`, `cdr_link`, `formstack`, `opensearch_dashboard`
|
||||
|
||||
```bash
|
||||
git -C /tmp/zammad-upstream diff <current-version> <target-version> -- db/migrate/ | grep -i 'signal\|whatsapp\|formstack\|opensearch'
|
||||
```
|
||||
|
||||
### 7. Frontend Build System
|
||||
|
||||
Check if the Vite/asset pipeline configuration has changed significantly, since our addon relies on being compiled into the Zammad frontend:
|
||||
|
||||
```bash
|
||||
git -C /tmp/zammad-upstream diff --stat <current-version> <target-version> -- vite.config.ts app/frontend/vite.config.ts config/initializers/assets.rb Gemfile
|
||||
```
|
||||
|
||||
Also check if CoffeeScript/Sprockets support has been removed (would break our legacy UI files):
|
||||
```bash
|
||||
git -C /tmp/zammad-upstream show <target-version>:Gemfile 2>/dev/null | grep -i 'coffee\|sprockets'
|
||||
```
|
||||
|
||||
## Report Format
|
||||
|
||||
Compile all findings into a structured report:
|
||||
|
||||
```
|
||||
## Zammad Compatibility Report: <current-version> -> <target-version>
|
||||
|
||||
### CRITICAL (Action Required Before Upgrade)
|
||||
- [List files that changed upstream AND are replaced by our addon - these need manual merging]
|
||||
- [List any broken monkey-patch targets]
|
||||
- [List any path collisions]
|
||||
|
||||
### WARNING (Review Needed)
|
||||
- [List API surface changes that could affect our code]
|
||||
- [List Dockerfile patch targets that changed]
|
||||
- [List build system changes]
|
||||
|
||||
### INFO (No Action Needed)
|
||||
- [List files checked with no changes]
|
||||
- [List confirmed-safe paths]
|
||||
|
||||
### Recommended Actions
|
||||
- For each CRITICAL item, describe what needs to be done
|
||||
- Note any files that should be re-copied from upstream and re-patched
|
||||
```
|
||||
|
||||
For each changed file in CRITICAL, show the upstream diff so the user can see what changed and decide how to integrate it.
|
||||
Loading…
Add table
Add a link
Reference in a new issue