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

---
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`, `cdrWhatsappMessage.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.