Add package conflict resolver

Makefile

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 SHELL := /bin/bash
-.PHONY: all iso iso-netinst iso-offline package sbom clean test help
+.PHONY: all iso iso-netinst iso-offline package sbom clean test test-conflicts help
 
 # Build configuration
 CODENAME := trixie
@@ -37,6 +37,7 @@ help:
 	@echo "  package PKG=x Build specific package (cx-core, cx-full, cx-archive-keyring)"
 	@echo "  sbom          Generate Software Bill of Materials"
 	@echo "  test          Run build verification tests"
+	@echo "  test-conflicts Run package conflict resolver tests"
 	@echo "  clean         Remove build artifacts"
 	@echo "  deps          Install build dependencies"
 	@echo ""
@@ -162,6 +163,10 @@ test:
 	./tests/verify-preseed.sh || true
 	@echo -e "$(GREEN)Tests complete$(NC)"
 
+test-conflicts:
+	@echo -e "$(GREEN)Running package conflict resolver tests...$(NC)"
+	./tests/resolve-conflicts-test.sh
+
 # Clean build artifacts
 clean:
 	@echo -e "$(YELLOW)Cleaning build artifacts...$(NC)"

apt/README.md

@@ -81,6 +81,59 @@ git commit -m "Add mypackage 1.0.0"
 git push
 ```
 
+## Package Conflict Checks
+
+`apt/scripts/resolve-conflicts.py` checks a planned install list before it is
+passed to the package manager. It reads normal APT `Conflicts` and `Breaks`
+metadata, and it can also read a small JSON rules file for CX-specific choices.
+
+Example:
+
+```bash
+apt/scripts/resolve-conflicts.py \
+  --rules ./package-conflicts.json \
+  docker.io podman
+```
+
+Example rules file:
+
+```json
+{
+  "conflicts": [
+    {
+      "packages": ["docker.io", "podman"],
+      "reason": "Both packages manage the default container runtime socket.",
+      "options": ["docker.io", "podman"]
+    }
+  ]
+}
+```
+
+The helper exits with status `1` when conflicts are found. A user choice can be
+saved and reused later:
+
+```bash
+apt/scripts/resolve-conflicts.py \
+  --rules ./package-conflicts.json \
+  --choice podman \
+  docker.io podman
+```
+
+For an interactive prompt:
+
+```bash
+apt/scripts/resolve-conflicts.py --interactive docker.io podman
+```
+
+In the installed `cx-core` package this is exposed through the wrapper:
+
+```bash
+cx resolve-conflicts docker.io podman
+```
+
+`cx install package-a package-b` also runs the same preflight check before it
+hands off to the Python package manager.
+
 ### Method 2: Workflow dispatch
 
 Go to Actions → Publish APT Repository → Run workflow