link-stack/.claude/skills/zammad-compat/SKILL.md

name	description	disable-model-invocation	argument-hint	allowed-tools
zammad-compat	Check upstream Zammad for breaking changes before upgrading the addon	true	[target-version]	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:

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:

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':

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:

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:

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:

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

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:

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):

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.