@synopackageland/cli 0.3.1 → 0.3.2

package/dist/error-registry.js

@@ -0,0 +1,827 @@
+export const ERROR_REGISTRY = {
+    // --- Contract Validation ---
+    CONTRACT_SCHEMA_UNSUPPORTED: {
+        code: "CONTRACT_SCHEMA_UNSUPPORTED",
+        description: "synology-app.yaml 的 schema 版本不受支援。",
+        suggestion: "請將 synology-app.yaml 的 schema 欄位設為 1。",
+    },
+    CONTRACT_MISSING_FIELD: {
+        code: "CONTRACT_MISSING_FIELD",
+        description: "synology-app.yaml 缺少必填欄位。",
+        suggestion: "請在 synology-app.yaml 補上缺少的必填欄位（例如 package, version, displayname 等）。",
+    },
+    CONTRACT_SCHEMA_INVALID: {
+        code: "CONTRACT_SCHEMA_INVALID",
+        description: "synology-app.yaml 格式與 JSON Schema 規格不符。",
+        suggestion: "請修正 synology-app.yaml 的欄位格式以符合規範。",
+    },
+    CONTRACT_PACKAGE_TOO_LONG: {
+        code: "CONTRACT_PACKAGE_TOO_LONG",
+        description: "Package Identity 超過 DSM 上限 32 字元。",
+        suggestion: "請縮短 synology-app.yaml 中的 package 名稱至 32 字元以內。",
+    },
+    CONTRACT_ADMINPORT_INVALID: {
+        code: "CONTRACT_ADMINPORT_INVALID",
+        description: "adminport 必須是整數。",
+        suggestion: "請在 synology-app.yaml 提供與 Compose published port 對應的整數 adminport。",
+    },
+    CONTRACT_ADMINPORT_UNMAPPED: {
+        code: "CONTRACT_ADMINPORT_UNMAPPED",
+        description: "adminport 未在 Compose ports 宣告中對應到容器 port。",
+        suggestion: "請在 compose.yaml 的 ports 區塊宣告與 adminport 對應的連接埠映射（例如 \"8080:80\"）。",
+    },
+    CONTRACT_LAUNCH_INVALID: {
+        code: "CONTRACT_LAUNCH_INVALID",
+        description: "integration.web.launch 模式無效。",
+        suggestion: "請改為 dsm-window（DSM 視窗，預設）或 new-page（新分頁），Headless App 請省略此欄位。",
+    },
+    CONTRACT_LAUNCH_REQUIRES_WEB: {
+        code: "CONTRACT_LAUNCH_REQUIRES_WEB",
+        description: "Headless App 不需要宣告 Web Launch Mode。",
+        suggestion: "請省略 integration.web.launch，或補上對應 Compose published port 的 adminport。",
+    },
+    CONTRACT_INVALID_STRING: {
+        code: "CONTRACT_INVALID_STRING",
+        description: "合約字串含有不允許的控制字元或未允許的插值語法。",
+        suggestion: "請移除控制字元與 ${ 插值語法，安裝參數請在 install 區塊宣告。",
+    },
+    CONTRACT_DSM_USER_DUPLICATE: {
+        code: "CONTRACT_DSM_USER_DUPLICATE",
+        description: "每顆 App 至多宣告一個 dsm_user 安裝參數。",
+        suggestion: "請在 synology-app.yaml 只保留一個 Container Run-as 參數。",
+    },
+    INSTALL_STRING_TOO_LONG: {
+        code: "INSTALL_STRING_TOO_LONG",
+        description: "Install Parameter 字串預設值超過 256 字元。",
+        suggestion: "請縮短 synology-app.yaml 中 install 參數的預設字串長度。",
+    },
+    INSTALL_STRING_INVALID: {
+        code: "INSTALL_STRING_INVALID",
+        description: "Install Parameter 字串值含有不合法字元或插值。",
+        suggestion: "請移除 install 參數預設值中的控制字元與 ${ 插值語法。",
+    },
+    INSTALL_PARAMETER_UNREFERENCED: {
+        code: "INSTALL_PARAMETER_UNREFERENCED",
+        description: "install 宣告的參數未在 Compose 中被引用。",
+        suggestion: "請在 compose.yaml 以 ${參數名稱} 引用該參數，或從 synology-app.yaml 移除未使用的宣告。",
+    },
+    INSTALL_DSM_USER_UNREFERENCED: {
+        code: "INSTALL_DSM_USER_UNREFERENCED",
+        description: "dsm_user 參數未在 Compose 中完整引用 UID 與 GID。",
+        suggestion: "請在 compose.yaml 將容器 user 或 PUID/PGID 設為 ${NAME_UID}:${NAME_GID}。",
+    },
+    CONTRACT_HOMES_PATH_FORBIDDEN: {
+        code: "CONTRACT_HOMES_PATH_FORBIDDEN",
+        description: "homes Install Parameter 不得在契約中寫入 NAS 實體路徑或預設值。",
+        suggestion: "請只宣告 type: homes 並在 Compose 引用該參數，由 glue／Broker 在安裝時解析這台 NAS 的 User Home 路徑。",
+    },
+    CONTRACT_POSIX_ALL_SHARES_VALUE_FORBIDDEN: {
+        code: "CONTRACT_POSIX_ALL_SHARES_VALUE_FORBIDDEN",
+        description: "POSIX all-shares 參數不得在契約中指定 default 或 NAS 實體路徑。",
+        suggestion: "請只宣告 type: posix_all_shares，讓 Broker 在安裝時用 DSM API 建立 Share snapshot。",
+    },
+    DSM_USER_REQUIRED: {
+        code: "DSM_USER_REQUIRED",
+        description: "有 Shared Folder 時必須宣告恰好一個 dsm_user 作為 Container Run-as。",
+        suggestion: "請在 synology-app.yaml 新增 install.<NAME>.type: dsm_user，並在 Compose 引用 ${NAME_UID}:${NAME_GID}。",
+    },
+    // --- Compose / Security Validation ---
+    PROJECT_RUNTIME_EXCLUSIVE: {
+        code: "PROJECT_RUNTIME_EXCLUSIVE",
+        description: "專案同時存在 compose.yaml 與 native.yaml，兩者互斥。",
+        suggestion: "請選擇使用 compose.yaml（容器 App）或 native.yaml（原生 App），並刪除另一個檔案。",
+    },
+    COMPOSE_MISSING: {
+        code: "COMPOSE_MISSING",
+        description: "找不到 compose.yaml 或 native.yaml。",
+        suggestion: "請在專案根目錄建立 compose.yaml 或 native.yaml。",
+    },
+    COMPOSE_SERVICE_NOT_FOUND: {
+        code: "COMPOSE_SERVICE_NOT_FOUND",
+        description: "depends_on 引用的服務不存在於 compose.yaml 中。",
+        suggestion: "請修正 compose.yaml 中的 depends_on，指向正確已定義的 service 名稱。",
+    },
+    COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN: {
+        code: "COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN",
+        description: "會走 DSM Docker Project resource worker 的 Compose command/entrypoint 陣列含純數字字串，可能在 worker YAML round-trip 後變成整數而無法 acquire。",
+        suggestion: "請把整個命令包成單一字串，例如 command: [\"sh\", \"-c\", \"httpd -f -p 8080 -h /srv\"]，或與 flag 併寫成 \"-p8080\"。",
+    },
+    COMPOSE_DYNAMIC_ROUTE_UNSUPPORTED: {
+        code: "COMPOSE_DYNAMIC_ROUTE_UNSUPPORTED",
+        description: "Compose dynamic route 超出 D1/D2 白名單，或使用 DSM worker 不會載入的 secret/config 來源。",
+        suggestion: "請只使用 string/boolean wizard answer 的 ${NAME} interpolation；secret/config 因 DSM worker 不讀 docker-compose.override.yml 而拒收。",
+    },
+    COMPOSE_BUILD_FORBIDDEN: {
+        code: "COMPOSE_BUILD_FORBIDDEN",
+        description: "D0 Compose route 禁止在 NAS install-time 使用 build:；build capability 永久拒收。",
+        suggestion: "請移除 build:，改用已存在的 image（最好使用 image@sha256:... 固定 digest），再重新執行 validate。",
+    },
+    COMPOSE_SOCKET_MOUNT_FORBIDDEN: {
+        code: "COMPOSE_SOCKET_MOUNT_FORBIDDEN",
+        description: "嚴禁掛載 Docker Socket 或系統敏感 Socket。",
+        suggestion: "請從 compose.yaml 移除 docker.sock 掛載；如需存取檔案請改用 shared_folder 或 File Gateway。",
+    },
+    COMPOSE_BIND_SOURCE_FORBIDDEN: {
+        code: "COMPOSE_BIND_SOURCE_FORBIDDEN",
+        description: "掛載來源路徑不合法或屬於受保護的系統路徑。",
+        suggestion: "請使用受控的 ${SYNOPKG_PKGVAR}、${SYNO_APP_SECRETS_DIR} 或已宣告的 ${SHARED_FOLDER} 槽位。",
+    },
+    COMPOSE_BIND_SOURCE_UNDECLARED: {
+        code: "COMPOSE_BIND_SOURCE_UNDECLARED",
+        description: "Volume 掛載使用了未宣告的 Shared Folder 變數。",
+        suggestion: "請先在 synology-app.yaml 的 install 區塊宣告該 shared_folder 參數。",
+    },
+    COMPOSE_BIND_SUFFIX_INVALID: {
+        code: "COMPOSE_BIND_SUFFIX_INVALID",
+        description: "Shared Folder 子路徑格式不合法（含有 .. 或控制字元）。",
+        suggestion: "請改用合法的相對子路徑，例如 ${MEDIA_SHARE}/data:/data。",
+    },
+    COMPOSE_POSIX_ALL_SHARES_UNDECLARED: {
+        code: "COMPOSE_POSIX_ALL_SHARES_UNDECLARED",
+        description: "Compose 使用了未宣告的 POSIX all-shares marker。",
+        suggestion: "請宣告 type: posix_all_shares，讓 Broker 透過 DSM API 建立安裝當下的 Share snapshot。",
+    },
+    COMPOSE_POSIX_ALL_SHARES_SUFFIX_FORBIDDEN: {
+        code: "COMPOSE_POSIX_ALL_SHARES_SUFFIX_FORBIDDEN",
+        description: "POSIX all-shares marker 不得附加 Share 子路徑。",
+        suggestion: "請只使用完整的 ${ALL_SHARES} source；每個 Share 的 container target 由 Broker 展開。",
+    },
+    COMPOSE_HOST_BIND_FORBIDDEN: {
+        code: "COMPOSE_HOST_BIND_FORBIDDEN",
+        description: "禁止直接硬編碼本機路徑（例如 /volume1/... 或 ./）。",
+        suggestion: "請在 synology-app.yaml 宣告 shared_folder 參數，並在 Compose 改用 ${SLOT} 引用。",
+    },
+    COMPOSE_NAMED_VOLUME_UNDECLARED: {
+        code: "COMPOSE_NAMED_VOLUME_UNDECLARED",
+        description: "服務使用了未在頂層 volumes 宣告的 Named Volume。",
+        suggestion: "請在 compose.yaml 頂層 volumes 區塊補上該 Volume 宣告，或改用受控目錄。",
+    },
+    COMPOSE_USER_ROOT_FORBIDDEN: {
+        code: "COMPOSE_USER_ROOT_FORBIDDEN",
+        description: "容器以 root (0:0) 執行，違反最小權限原則。",
+        suggestion: "請在 synology-app.yaml 宣告 dsm_user 並在 Compose 使用 ${USER_UID}:${USER_GID}。",
+    },
+    COMPOSE_USER_NUMERIC_FORBIDDEN: {
+        code: "COMPOSE_USER_NUMERIC_FORBIDDEN",
+        description: "禁止在 compose.yaml 硬編碼數字 uid:gid。",
+        suggestion: "請在 synology-app.yaml 宣告 dsm_user，並在 Compose 引用 ${NAME_UID}:${NAME_GID}。",
+    },
+    COMPOSE_PRIVILEGED_FORBIDDEN: {
+        code: "COMPOSE_PRIVILEGED_FORBIDDEN",
+        description: "使用了 privileged: true 但未在合約宣告。",
+        suggestion: "請在 synology-app.yaml 加上 privilege.privileged: true，或移除 privileged: true。",
+    },
+    COMPOSE_HOST_NETWORK_FORBIDDEN: {
+        code: "COMPOSE_HOST_NETWORK_FORBIDDEN",
+        description: "使用了 host network 模式但未在合約宣告。",
+        suggestion: "請在 synology-app.yaml 加上 privilege.host_network: true，或改用受控網路模式。",
+    },
+    COMPOSE_HOST_PID_FORBIDDEN: {
+        code: "COMPOSE_HOST_PID_FORBIDDEN",
+        description: "使用了 pid: host 但未在合約宣告。",
+        suggestion: "請在 synology-app.yaml 加上 privilege.host_pid: true，或移除 pid: host。",
+    },
+    COMPOSE_HOST_IPC_FORBIDDEN: {
+        code: "COMPOSE_HOST_IPC_FORBIDDEN",
+        description: "使用了 ipc: host 但未在合約宣告。",
+        suggestion: "請在 synology-app.yaml 加上 privilege.host_ipc: true，或移除 ipc: host。",
+    },
+    COMPOSE_DEVICES_FORBIDDEN: {
+        code: "COMPOSE_DEVICES_FORBIDDEN",
+        description: "使用了 devices 裝置存取但未在合約宣告。",
+        suggestion: "請在 synology-app.yaml 加上 privilege.devices: true，或移除 devices 區塊。",
+    },
+    COMPOSE_CAP_ADD_FORBIDDEN: {
+        code: "COMPOSE_CAP_ADD_FORBIDDEN",
+        description: "使用了 cap_add 權限提升但未在合約宣告。",
+        suggestion: "請在 synology-app.yaml 加上 privilege.cap_add: true，或移除 cap_add 區塊。",
+    },
+    COMPOSE_ENV_MISSING: {
+        code: "COMPOSE_ENV_MISSING",
+        description: "專案缺少必要的環境變數目錄結構。",
+        suggestion: "請確認 SYNOPKG_PKGVAR 與 secrets 目錄已正確建立。",
+    },
+    COMPOSE_NOT_HEALTHY: {
+        code: "COMPOSE_NOT_HEALTHY",
+        description: "Compose 服務未能於時限內通過 healthcheck 達到 healthy 狀態。",
+        suggestion: "請檢查容器健康檢查設定與應用程式日誌：synopkgland log --host <nas>。",
+    },
+    COMPOSE_NOT_RUNNING: {
+        code: "COMPOSE_NOT_RUNNING",
+        description: "Compose 服務未能於時限內維持 running 狀態。",
+        suggestion: "請檢查容器啟動腳本與日誌以排除崩潰原因：synopkgland log --host <nas>。",
+    },
+    // --- Native Validation / Payload ---
+    NATIVE_LOAD_FAILED: {
+        code: "NATIVE_LOAD_FAILED",
+        description: "無法讀取或解析 native.yaml。",
+        suggestion: "請確認 native.yaml 存在且為合法 YAML 格式。",
+    },
+    NATIVE_SCHEMA_INVALID: {
+        code: "NATIVE_SCHEMA_INVALID",
+        description: "native.yaml schema 版本無效（必須為整數 1）。",
+        suggestion: "請在 native.yaml 設定 schema: 1。",
+    },
+    NATIVE_TARGETS_REQUIRED: {
+        code: "NATIVE_TARGETS_REQUIRED",
+        description: "native.yaml 缺少 targets 區塊。",
+        suggestion: "請在 native.yaml 宣告 targets 區塊並指定 x86_64 或 aarch64 目標。",
+    },
+    NATIVE_TARGETS_EMPTY: {
+        code: "NATIVE_TARGETS_EMPTY",
+        description: "native.yaml 中的 targets 區塊不可為空。",
+        suggestion: "請在 native.yaml 的 targets 內至少定義一個架構目標（x86_64 或 aarch64）。",
+    },
+    NATIVE_ARCH_UNKNOWN: {
+        code: "NATIVE_ARCH_UNKNOWN",
+        description: "native.yaml 定義了不受支援的架構目標名稱。",
+        suggestion: "目標架構名稱僅支援 x86_64 與 aarch64。",
+    },
+    NATIVE_TARGET_INVALID: {
+        code: "NATIVE_TARGET_INVALID",
+        description: "native.yaml 目標架構定義無效。",
+        suggestion: "每個目標架構必須包含 path 或 url 下載來源設定。",
+    },
+    NATIVE_TARGET_NOT_DECLARED: {
+        code: "NATIVE_TARGET_NOT_DECLARED",
+        description: "欲建置或部署的架構目標未在 native.yaml 中宣告。",
+        suggestion: "請在 native.yaml 的 targets 補上該架構目標，或透過 --arch 指定已宣告的目標。",
+    },
+    NATIVE_TARGET_SOURCE_EXCLUSIVE: {
+        code: "NATIVE_TARGET_SOURCE_EXCLUSIVE",
+        description: "目標架構不可同時包含 path 與 url，兩者互斥。",
+        suggestion: "請在該目標架構中只保留 path（本機）或 url（遠端二進位檔）。",
+    },
+    NATIVE_PATH_FORBIDDEN_IN_LISTING: {
+        code: "NATIVE_PATH_FORBIDDEN_IN_LISTING",
+        description: "公開上架審查禁止使用本機 path 來源的 native 目標。",
+        suggestion: "請將 target 改為公開可下載的 url 並附帶 sha256 校驗碼。",
+    },
+    NATIVE_SHA256_REQUIRED_IN_LISTING: {
+        code: "NATIVE_SHA256_REQUIRED_IN_LISTING",
+        description: "公開上架審查要求 url 目標必須提供 sha256 校驗碼。",
+        suggestion: "請在 native.yaml 的 url 目標補上 64 位十六進位 sha256 欄位。",
+    },
+    NATIVE_SHA256_INVALID: {
+        code: "NATIVE_SHA256_INVALID",
+        description: "sha256 校驗碼格式無效。",
+        suggestion: "請提供恰好 64 字元的十六進位 SHA-256 字串。",
+    },
+    NATIVE_STRIP_COMPONENTS_INVALID: {
+        code: "NATIVE_STRIP_COMPONENTS_INVALID",
+        description: "strip_components 必須是非負整數。",
+        suggestion: "請在 native.yaml 將 strip_components 設為大於等於 0 的整數。",
+    },
+    NATIVE_SERVICE_REQUIRED: {
+        code: "NATIVE_SERVICE_REQUIRED",
+        description: "native.yaml 缺少 service 區塊。",
+        suggestion: "請在 native.yaml 補上 service 區塊並宣告 exec 與 args/env。",
+    },
+    NATIVE_SERVICE_USER_FORBIDDEN: {
+        code: "NATIVE_SERVICE_USER_FORBIDDEN",
+        description: "native service 不允許自訂 user 欄位（固定以 package 使用者執行）。",
+        suggestion: "請從 native.yaml 的 service 區塊移除 user 欄位。",
+    },
+    NATIVE_SERVICE_SHELL_FIELD_FORBIDDEN: {
+        code: "NATIVE_SERVICE_SHELL_FIELD_FORBIDDEN",
+        description: "禁止在 native service 使用 command/shell 等字串欄位以免 shell injection。",
+        suggestion: "請改用 exec（路徑）與 args（字串陣列）方式宣告啟動指令。",
+    },
+    NATIVE_EXEC_REQUIRED: {
+        code: "NATIVE_EXEC_REQUIRED",
+        description: "native service 缺少 exec 執行檔路徑。",
+        suggestion: "請在 native.yaml 的 service 區塊指定 exec: <相對路徑>。",
+    },
+    NATIVE_EXEC_INVALID_PATH: {
+        code: "NATIVE_EXEC_INVALID_PATH",
+        description: "exec 必須是相對路徑，且不可包含 .. 或絕對路徑。",
+        suggestion: "請指定相對於安裝根目錄的合法相對路徑，例如 exec: bin/app。",
+    },
+    NATIVE_ARGS_INVALID: {
+        code: "NATIVE_ARGS_INVALID",
+        description: "service.args 必須是字串陣列。",
+        suggestion: "請在 native.yaml 將 args 宣告為字串列表格式（例如 args: [\"--port\", \"8080\"]）。",
+    },
+    NATIVE_ENV_INVALID: {
+        code: "NATIVE_ENV_INVALID",
+        description: "service.env 必須是 key-value 字串映射表。",
+        suggestion: "請將 env 宣告為字典物件且每個值皆為字串。",
+    },
+    NATIVE_PKGVAR_REQUIRED: {
+        code: "NATIVE_PKGVAR_REQUIRED",
+        description: "原生二進位 App 必須在 args 或 env 中引用 ${SYNOPKG_PKGVAR} 以指定資料路徑。",
+        suggestion: "請在 native.yaml 的 service.args 或 service.env 加入 ${SYNOPKG_PKGVAR} 參數。",
+    },
+    NATIVE_ARCH_FAMILY_REQUIRED: {
+        code: "NATIVE_ARCH_FAMILY_REQUIRED",
+        description: "建置原生 SPK 時缺少目標架構家族（x86_64 或 aarch64）。",
+        suggestion: "請在指令加上 --arch x86_64 或 --arch aarch64。",
+    },
+    NATIVE_ARCH_UNDETERMINED: {
+        code: "NATIVE_ARCH_UNDETERMINED",
+        description: "無法從目標 NAS 的 CPU 資訊自動判定架構家族。",
+        suggestion: "請使用 --arch x86_64 或 --arch aarch64 明確指定目標架構。",
+    },
+    NATIVE_PAYLOAD_BUNDLE_COLLISION: {
+        code: "NATIVE_PAYLOAD_BUNDLE_COLLISION",
+        description: "原生 payload 解壓縮內容與 App Bundle 核心保留檔衝突。",
+        suggestion: "請檢查 payload 內容，避免在根目錄覆蓋 synology-app.yaml 或 native.yaml。",
+    },
+    NATIVE_PAYLOAD_DOWNLOAD_FAILED: {
+        code: "NATIVE_PAYLOAD_DOWNLOAD_FAILED",
+        description: "下載原生二進位檔 payload 失敗。",
+        suggestion: "請檢查 native.yaml 中的 url 是否有效且網路連線正常。",
+    },
+    NATIVE_PAYLOAD_DOWNLOAD_INVALID: {
+        code: "NATIVE_PAYLOAD_DOWNLOAD_INVALID",
+        description: "下載的原生 payload 回傳內容無效。",
+        suggestion: "請確認目標 URL 回傳了有效的二進位檔案內容。",
+    },
+    NATIVE_PAYLOAD_DUPLICATE_ENTRY: {
+        code: "NATIVE_PAYLOAD_DUPLICATE_ENTRY",
+        description: "原生 payload 壓縮檔內包含重複的檔案路徑。",
+        suggestion: "請重新打包原始檔案，確保壓縮檔內無重複 entry。",
+    },
+    NATIVE_PAYLOAD_ERROR: {
+        code: "NATIVE_PAYLOAD_ERROR",
+        description: "處理原生二進位 payload 時發生未預期錯誤。",
+        suggestion: "請檢查 payload 壓縮檔完整性或重新建置 SPK。",
+    },
+    NATIVE_PAYLOAD_EXTRACTION_FAILED: {
+        code: "NATIVE_PAYLOAD_EXTRACTION_FAILED",
+        description: "解壓縮原生二進位 payload 失敗。",
+        suggestion: "請確認壓縮檔格式正確無損壞，且支援 tar.gz / tar.xz / zip。",
+    },
+    NATIVE_PAYLOAD_INVALID_HARDLINK: {
+        code: "NATIVE_PAYLOAD_INVALID_HARDLINK",
+        description: "原生 payload 含有無效或循環的 hardlink。",
+        suggestion: "請移除壓縮檔中不合法的 hardlink 後重新打包。",
+    },
+    NATIVE_PAYLOAD_INVALID_STRIP_COMPONENTS: {
+        code: "NATIVE_PAYLOAD_INVALID_STRIP_COMPONENTS",
+        description: "strip_components 設定超過了壓縮檔目錄層級深度。",
+        suggestion: "請在 native.yaml 調整或減少 strip_components 數值。",
+    },
+    NATIVE_PAYLOAD_INVALID_SYMLINK: {
+        code: "NATIVE_PAYLOAD_INVALID_SYMLINK",
+        description: "原生 payload 含有無效的符號連結。",
+        suggestion: "請檢查壓縮檔內的 symlink 目標是否存在且合法。",
+    },
+    NATIVE_PAYLOAD_INVALID_ZIP: {
+        code: "NATIVE_PAYLOAD_INVALID_ZIP",
+        description: "ZIP 壓縮檔格式無效或已損壞。",
+        suggestion: "請檢查 zip 檔案完整性或重新打包。",
+    },
+    NATIVE_PAYLOAD_SHA256_MISMATCH: {
+        code: "NATIVE_PAYLOAD_SHA256_MISMATCH",
+        description: "下載的 payload SHA-256 校驗碼與 native.yaml 宣告不符。",
+        suggestion: "請更新 native.yaml 中的 sha256 欄位以符合實際檔案雜湊。",
+    },
+    NATIVE_PAYLOAD_SOURCE_AMBIGUOUS: {
+        code: "NATIVE_PAYLOAD_SOURCE_AMBIGUOUS",
+        description: "目標架構同時宣告了 path 與 url，來源衝突。",
+        suggestion: "請在該目標架構中只保留 path 或 url 其中一種來源。",
+    },
+    NATIVE_PAYLOAD_SOURCE_REQUIRED: {
+        code: "NATIVE_PAYLOAD_SOURCE_REQUIRED",
+        description: "目標架構缺少 path 或 url 來源設定。",
+        suggestion: "請在 native.yaml 的 targets 內為各架構補上 path 或 url。",
+    },
+    NATIVE_PAYLOAD_SYMLINK_CYCLE: {
+        code: "NATIVE_PAYLOAD_SYMLINK_CYCLE",
+        description: "原生 payload 包含循環符號連結 (Symlink cycle)。",
+        suggestion: "請移除壓縮檔中的循環 symlink。",
+    },
+    NATIVE_PAYLOAD_UNSAFE_HARDLINK: {
+        code: "NATIVE_PAYLOAD_UNSAFE_HARDLINK",
+        description: "原生 payload hardlink 試圖連結至目標目錄外。",
+        suggestion: "請確保 hardlink 僅指向 payload 目錄內部的有效檔案。",
+    },
+    NATIVE_PAYLOAD_UNSAFE_PATH: {
+        code: "NATIVE_PAYLOAD_UNSAFE_PATH",
+        description: "原生 payload 含有路徑穿越 (Path traversal) 等不安全路徑。",
+        suggestion: "請確保壓縮檔內無包含 .. 或絕對路徑的檔案名稱。",
+    },
+    NATIVE_PAYLOAD_UNSAFE_SYMLINK: {
+        code: "NATIVE_PAYLOAD_UNSAFE_SYMLINK",
+        description: "原生 payload symlink 指向了安裝目錄之外。",
+        suggestion: "請確保 symlink 僅指向 payload 目錄內部的相對目標。",
+    },
+    NATIVE_PAYLOAD_UNSUPPORTED_ENTRY: {
+        code: "NATIVE_PAYLOAD_UNSUPPORTED_ENTRY",
+        description: "原生 payload 包含不支援的特殊檔案類型（如 device node 或 fifo）。",
+        suggestion: "請從壓縮檔中移除特殊檔案，僅保留一般檔案、目錄與合法 symlink。",
+    },
+    NATIVE_PAYLOAD_UNSUPPORTED_ZIP: {
+        code: "NATIVE_PAYLOAD_UNSUPPORTED_ZIP",
+        description: "不支援的 ZIP 特性（例如 ZIP64、多卷分割或密碼加密）。",
+        suggestion: "請使用標準未加密的 ZIP 或改用 tar.gz 打包。",
+    },
+    NATIVE_PAYLOAD_XZ_FAILED: {
+        code: "NATIVE_PAYLOAD_XZ_FAILED",
+        description: "解壓縮 tar.xz 失敗。",
+        suggestion: "請確認本機已安裝 xz 工具且檔案未損壞。",
+    },
+    NATIVE_PAYLOAD_XZ_UNAVAILABLE: {
+        code: "NATIVE_PAYLOAD_XZ_UNAVAILABLE",
+        description: "系統中找不到 xz 指令可用於解壓縮 .tar.xz 檔案。",
+        suggestion: "請在作業系統中安裝 xz-utils 或改用 tar.gz 格式打包。",
+    },
+    // --- SPK Build & Attestation ---
+    EMBEDDED_ATTESTATION_TOKEN_EMPTY: {
+        code: "EMBEDDED_ATTESTATION_TOKEN_EMPTY",
+        description: "建置 Curated SPK 時嵌入的 Attestation Token 為空。",
+        suggestion: "請檢查 CI Attestation 簽章步驟是否正常產出 JWT。",
+    },
+    BUILD_SPK_FAILED: {
+        code: "BUILD_SPK_FAILED",
+        description: "SPK 打包流程失敗。",
+        suggestion: "請檢查 validate 錯誤與目錄檔案權限後重試。",
+    },
+    // --- Deploy & Host ---
+    VALIDATION_FAILED: {
+        code: "VALIDATION_FAILED",
+        description: "專案未通過契約或安全驗證，終止部署。",
+        suggestion: "請先執行 synopkgland validate 排除合約與 Compose 錯誤。",
+    },
+    DEPLOY_FAILED: {
+        code: "DEPLOY_FAILED",
+        description: "部署至 NAS 時發生未分類錯誤。",
+        suggestion: "請檢查 NAS 網路連線與日誌：synopkgland log --host <nas>。",
+    },
+    DEPLOY_PERSONAL_BUILD_EXHAUSTED: {
+        code: "DEPLOY_PERSONAL_BUILD_EXHAUSTED",
+        description: "Personal App 的 Package Build 已用盡 0001–9999 命名範圍。",
+        suggestion: "請改用新的 App Version，或先清理並確認不會與 Curated 版本命名空間混用。",
+    },
+    SHARE_VALUE_REQUIRED: {
+        code: "SHARE_VALUE_REQUIRED",
+        description: "部署時缺少合約中宣告的 shared_folder 實際路徑映射。",
+        suggestion: "請使用 --share <SLOT>=<邏輯名> 提供對應的 Shared Folder 名稱。",
+    },
+    SHARE_LOGICAL_NAME_REQUIRED: {
+        code: "SHARE_LOGICAL_NAME_REQUIRED",
+        description: "Share 參數必須提供邏輯名稱，禁止使用 /volume1/... 等實體路徑。",
+        suggestion: "請指定 DSM 控制台中的 Shared Folder 邏輯名稱，例如 --share MEDIA_SHARE=photos。",
+    },
+    SHARE_NOT_FOUND: {
+        code: "SHARE_NOT_FOUND",
+        description: "在目標 NAS 上找不到指定的 Shared Folder。",
+        suggestion: "請在 DSM 控制台建立該 Shared Folder，或檢查名稱拼字。",
+    },
+    HOMES_NOT_ENABLED: {
+        code: "HOMES_NOT_ENABLED",
+        description: "目標 NAS 未啟用 User Home，或無法解析 homes 的實體 bind source。",
+        suggestion: "請在這台 NAS 啟用 DSM User Home，並確認 Broker／glue 能回傳解析後的路徑，再重新部署。",
+    },
+    DSM_USER_LOGICAL_NAME_REQUIRED: {
+        code: "DSM_USER_LOGICAL_NAME_REQUIRED",
+        description: "dsm_user 參數必須提供 DSM 使用者邏輯名稱，禁止使用數字 UID。",
+        suggestion: "請在 --run-as 指定 DSM 使用者帳號名稱（例如 --run-as RUN_AS=alice）。",
+    },
+    CURATED_DEPLOY_REFUSED: {
+        code: "CURATED_DEPLOY_REFUSED",
+        description: "目標 NAS 已持有 Curated App Package Attestation，禁止隨意覆蓋部署。",
+        suggestion: "請改用 --dev 部署至開發隔離環境，或加上 --replace-curated 明確降級。",
+    },
+    CATALOG_PUBLISH_FAILED: {
+        code: "CATALOG_PUBLISH_FAILED",
+        description: "發布 SPK 至 Package Source 失敗。",
+        suggestion: "請確認 Package Source 服務運作正常且網路可達。",
+    },
+    LOCAL_SPK_INSTALL_UNSUPPORTED: {
+        code: "LOCAL_SPK_INSTALL_UNSUPPORTED",
+        description: "目標主機介面不支援直接安裝本機 SPK。",
+        suggestion: "請透過 Package Center 或支援 local-spk 安裝的 Host Adapter 進行部署。",
+    },
+    CATALOG_INSTALL_FAILED: {
+        code: "CATALOG_INSTALL_FAILED",
+        description: "NAS Package Center 安裝套件失敗。",
+        suggestion: "請至 DSM Package Center 檢查安裝日誌或手動嘗試安裝。",
+    },
+    DEPLOY_PARAM_UNDECLARED: {
+        code: "DEPLOY_PARAM_UNDECLARED",
+        description: "deploy --param 提供了契約未宣告的 Install Parameter。",
+        suggestion: "請只傳 synology-app.yaml install 中宣告的 string 或 boolean 名稱。",
+    },
+    DEPLOY_PARAM_TYPE_INVALID: {
+        code: "DEPLOY_PARAM_TYPE_INVALID",
+        description: "deploy --param 的值不符合契約宣告的 string 或 boolean 型別。",
+        suggestion: "string 請傳非空字串；boolean 請只傳 true 或 false。",
+    },
+    DSM_DEPENDENCY_CONFLICT: {
+        code: "DSM_DEPENDENCY_CONFLICT",
+        description: "DSM 複合安裝請求因執行中的依賴套件而拒絕。",
+        suggestion: "請先停止列出的依賴套件再重試升級。",
+    },
+    DSM_COMPOUND_FAILED: {
+        code: "DSM_COMPOUND_FAILED",
+        description: "DSM 複合安裝請求的子步驟失敗。",
+        suggestion: "請檢查回應中的 api、method、errorCode 與 DSM Package Center 日誌後重試。",
+    },
+    DSM_REQUEST_FAILED: {
+        code: "DSM_REQUEST_FAILED",
+        description: "DSM SYNO.Entry.Request 複合請求失敗。",
+        suggestion: "請檢查 DSM session、請求參數與 Package Center 日誌後重試。",
+    },
+    INNER_LOOP_API_MISSING: {
+        code: "INNER_LOOP_API_MISSING",
+        description: "目標 NAS 上的 SynoPkgLandService Broker inner-loop API 不可用。",
+        suggestion: "請確認已在 NAS 安裝並啟動 SynoPkgLandService (Broker >= 0.1.0-0016)。",
+    },
+    ATTESTATION_FAILED: {
+        code: "ATTESTATION_FAILED",
+        description: "向 NAS 申請或驗證 Local Attestation 失敗。",
+        suggestion: "請檢查 DSM 登入身分是否為管理者，以及 Broker 運作狀態。",
+    },
+    NOT_INSTALLED: {
+        code: "NOT_INSTALLED",
+        description: "套件尚未在目標 NAS 上安裝部署。",
+        suggestion: "請先執行 synopkgland deploy --host <nas> 安裝套件。",
+    },
+    HOST_CREDENTIALS_MISSING: {
+        code: "HOST_CREDENTIALS_MISSING",
+        description: "找不到目標 NAS 的連線憑證。",
+        suggestion: "請在 ~/.synoagentcli/setting.json 設定 profile，或設定 DSM_URL 與 DSM_PASSWORD 環境變數。",
+    },
+    HOST_UNREACHABLE: {
+        code: "HOST_UNREACHABLE",
+        description: "無法連線至目標 NAS（連線逾時或網路不可達）。",
+        suggestion: "請檢查 NAS IP/網址與網路連線；Node 網路若遇 EHOSTUNREACH 可使用 curl fallback 模式。",
+    },
+    BROKER_NOT_INSTALLED: {
+        code: "BROKER_NOT_INSTALLED",
+        description: "目標 NAS 尚未安裝 SynoPkgLandService (Broker)。",
+        suggestion: "請至 DSM Package Center 安裝 SynoPkgLandService 套件。",
+    },
+    PACKAGE_BROKEN: {
+        code: "PACKAGE_BROKEN",
+        description: "套件在 DSM Package Center 處於損毀或安裝失敗狀態 (status 150 / broken)。",
+        suggestion: "請至 DSM Package Center 嘗試修復 (Repair) 或重新安裝套件。",
+    },
+    ATTESTATION_TRUST_ROOT_MISSING: {
+        code: "ATTESTATION_TRUST_ROOT_MISSING",
+        description: "Broker 缺少生產環境 Attestation Trust Root 信任根憑證。",
+        suggestion: "請確認 SynoPkgLandService 套件完整安裝且 trust root keyring 未被移除。",
+    },
+    ATTESTATION_MISSING: {
+        code: "ATTESTATION_MISSING",
+        description: "App Bundle 缺少必要的 Attestation 簽章憑證。",
+        suggestion: "請先透過 synopkgland deploy 簽發 Local Attestation 或透過 Curated CI 簽署。",
+    },
+    ATTESTATION_INVALID: {
+        code: "ATTESTATION_INVALID",
+        description: "Attestation Token 驗證失敗或與目前 App Bundle 雜湊不符。",
+        suggestion: "檔案修改後請重新執行 synopkgland deploy 產生並安裝新 Attestation。",
+    },
+    READINESS_TIMEOUT: {
+        code: "READINESS_TIMEOUT",
+        description: "App 容器未在時限內就緒 (Readiness Deadline)。",
+        suggestion: "請使用 synopkgland log --host <nas> 檢查容器啟動日誌與健康檢查。",
+    },
+    PROJECT_BINDING_NOT_FOUND: {
+        code: "PROJECT_BINDING_NOT_FOUND",
+        description: "在 Broker 中找不到此套件的 Project Binding 紀錄。",
+        suggestion: "請執行 synopkgland deploy --host <nas> 重新建立部署。",
+    },
+    PROJECT_BINDING_DRIFTED: {
+        code: "PROJECT_BINDING_DRIFTED",
+        description: "Container Manager 中的實際專案狀態與 Broker 綁定記錄不一致。",
+        suggestion: "請執行 synopkgland deploy --host <nas> 重新同步專案。",
+    },
+    PROJECT_BINDING_REMOVED: {
+        code: "PROJECT_BINDING_REMOVED",
+        description: "此套件的 Project Binding 已被標記為移除。",
+        suggestion: "請執行 synopkgland deploy --host <nas> 重新安裝套件。",
+    },
+    PROJECT_BINDING_UNKNOWN: {
+        code: "PROJECT_BINDING_UNKNOWN",
+        description: "Container Manager 暫時無法取得 Project 狀態。",
+        suggestion: "請至 DSM 確認 Container Manager 服務正常運作。",
+    },
+    CLI_VERSION_DRIFT: {
+        code: "CLI_VERSION_DRIFT",
+        description: "本機 @synopackageland/cli 版本與 CI TOOLCHAIN_VERSION 不一致。",
+        suggestion: "請更新 package.json / package-lock.json 或執行 npm install @synopackageland/cli@latest。",
+    },
+    PROJECT_FILES_MISSING: {
+        code: "PROJECT_FILES_MISSING",
+        description: "專案根目錄缺少核心檔案（synology-app.yaml, compose.yaml/native.yaml, README.md, icon.png）。",
+        suggestion: "請補齊缺失的專案核心檔案。",
+    },
+    TRUSTED_APP_ENTRY_FAILED: {
+        code: "TRUSTED_APP_ENTRY_FAILED",
+        description: "Trusted App Entry HTTP 探測失敗（回傳非 200 或無法連線）。",
+        suggestion: "請檢查 Web Station 入口與容器 Web 服務是否正常監聽 adminport。",
+    },
+    TEST_HOST_FAILED: {
+        code: "TEST_HOST_FAILED",
+        description: "在 NAS 上執行 Open smoke 測試失敗（無法取得 DSM User Context）。",
+        suggestion: "請檢查 App 是否正確呼叫 requireLogin 或檢查 DSM Session 登入態。",
+    },
+    // --- Curated Release & Trust Root ---
+    CURATED_TRUST_ROOT_MISSING: {
+        code: "CURATED_TRUST_ROOT_MISSING",
+        description: "缺少 Curated Public Keyring 信任根設定。",
+        suggestion: "請設定 SYNOPKGLAND_CURATED_ATTESTATION_KEYRING 或 SYNOPKGLAND_CURATED_ATTESTATION_KEYRING_PATH。",
+    },
+    CURATED_TRUST_ROOT_INVALID: {
+        code: "CURATED_TRUST_ROOT_INVALID",
+        description: "Curated Public Keyring 格式或內容無效。",
+        suggestion: "請確認信任根為合法 JSON 且包含合規的 RS256 公鑰物件。",
+    },
+    CURATED_SIGNING_KEY_UNKNOWN: {
+        code: "CURATED_SIGNING_KEY_UNKNOWN",
+        description: "簽署金鑰的 kid 不存在於 Curated Public Keyring 中。",
+        suggestion: "請確認所使用的簽署金鑰已登錄於受信任的 Keyring 信任根。",
+    },
+    CURATED_SIGNING_KEY_REVOKED: {
+        code: "CURATED_SIGNING_KEY_REVOKED",
+        description: "簽署金鑰已被標記為撤銷 (revoked)。",
+        suggestion: "請更換為有效且處於 active 狀態的簽署金鑰。",
+    },
+    CURATED_SIGNING_KEY_NOT_ACTIVE: {
+        code: "CURATED_SIGNING_KEY_NOT_ACTIVE",
+        description: "簽署金鑰非 active 狀態（可能為 verify-only）。",
+        suggestion: "請使用具備簽章權限的 active 簽署金鑰。",
+    },
+    CURATED_SIGNING_KEY_MISMATCH: {
+        code: "CURATED_SIGNING_KEY_MISMATCH",
+        description: "私鑰對應的公鑰內容與 Keyring 中登錄的公鑰不符。",
+        suggestion: "請檢查簽署金鑰與 Keyring 憑證是否匹配。",
+    },
+    CURATED_SIGNING_MATERIAL_MISSING: {
+        code: "CURATED_SIGNING_MATERIAL_MISSING",
+        description: "缺少 Curated 簽署私鑰環境變數。",
+        suggestion: "請設定 SYNOPKGLAND_CURATED_ATTESTATION_PRIVATE_JWK 或 PRIVATE_PKCS8。",
+    },
+    CURATED_SIGNING_MATERIAL_AMBIGUOUS: {
+        code: "CURATED_SIGNING_MATERIAL_AMBIGUOUS",
+        description: "同時設定了 JWK 與 PKCS8 私鑰環境變數，來源衝突。",
+        suggestion: "請僅保留 SYNOPKGLAND_CURATED_ATTESTATION_PRIVATE_JWK 或 PRIVATE_PKCS8 其中之一。",
+    },
+    CURATED_SIGNING_MATERIAL_INVALID: {
+        code: "CURATED_SIGNING_MATERIAL_INVALID",
+        description: "提供的簽署私鑰格式無效或無法匯入。",
+        suggestion: "請確認私鑰為合法未加密的 RS256 RSA 私鑰。",
+    },
+    CURATED_RELEASE_SIGNER_MISSING: {
+        code: "CURATED_RELEASE_SIGNER_MISSING",
+        description: "發布流程中未提供 Attestation 簽章器。",
+        suggestion: "請確認 CI 權限與 release custody 金鑰已正確注入。",
+    },
+    CURATED_RELEASE_FAILED: {
+        code: "CURATED_RELEASE_FAILED",
+        description: "Curated Release 發布流程失敗。",
+        suggestion: "請檢查 release CI 日誌以定位失敗步驟。",
+    },
+    CURATED_APP_NOT_FOUND: {
+        code: "CURATED_APP_NOT_FOUND",
+        description: "在 Community Apps 目錄中找不到目標 App。",
+        suggestion: "請確認 synopkgland-community-apps/apps/<package> 目錄存在。",
+    },
+    CURATED_APP_VERSION_REQUIRED: {
+        code: "CURATED_APP_VERSION_REQUIRED",
+        description: "發布時合約必須宣告 version 版本號。",
+        suggestion: "請在 synology-app.yaml 設定合法的 version（例如 1.0.0）。",
+    },
+    CURATED_BUILD_INVALID: {
+        code: "CURATED_BUILD_INVALID",
+        description: "Package Build 號碼格式無效（必須為四位數字）。",
+        suggestion: "請確保 build 號碼為四位數字字串（例如 0001）。",
+    },
+    CURATED_BUILD_MUST_NOT_BE_IN_SOURCE_VERSION: {
+        code: "CURATED_BUILD_MUST_NOT_BE_IN_SOURCE_VERSION",
+        description: "合約中的 version 不得包含 -build 後綴（Build 由 CI Ledger 分配）。",
+        suggestion: "請將 synology-app.yaml 的 version 改為純語意化版本（例如 1.0.0，不含 -0001）。",
+    },
+    CURATED_PACKAGE_IDENTITY_REQUIRED: {
+        code: "CURATED_PACKAGE_IDENTITY_REQUIRED",
+        description: "合約中缺少 package 識別碼宣告。",
+        suggestion: "請在 synology-app.yaml 設定 package 欄位。",
+    },
+    CURATED_DEVELOPMENT_IDENTITY_FORBIDDEN: {
+        code: "CURATED_DEVELOPMENT_IDENTITY_FORBIDDEN",
+        description: "Curated 上架發布嚴禁使用 .dev 開發後綴識別碼。",
+        suggestion: "請移除 package 名稱末尾的 .dev 後綴。",
+    },
+    CURATED_PACKAGE_DIRECTORY_MISMATCH: {
+        code: "CURATED_PACKAGE_DIRECTORY_MISMATCH",
+        description: "Community Apps 目錄名稱與 synology-app.yaml 中的 package 名稱不一致。",
+        suggestion: "請將 app 目錄重新命名為 apps/<package>。",
+    },
+    CURATED_VALIDATION_FAILED: {
+        code: "CURATED_VALIDATION_FAILED",
+        description: "專案未通過 Curated listing profile 嚴格驗證門檻。",
+        suggestion: "請執行 synopkgland validate 排除錯誤後再進行 release。",
+    },
+    CURATED_NATIVE_MISSING: {
+        code: "CURATED_NATIVE_MISSING",
+        description: "原生 App 發布時找不到 native.yaml 定義檔。",
+        suggestion: "請在專案根目錄補上 native.yaml。",
+    },
+    CURATED_NATIVE_TARGETS_EMPTY: {
+        code: "CURATED_NATIVE_TARGETS_EMPTY",
+        description: "原生 App 發布時 targets 不可為空。",
+        suggestion: "請在 native.yaml targets 至少定義一個架構目標。",
+    },
+    CURATED_COMPOSE_MISSING: {
+        code: "CURATED_COMPOSE_MISSING",
+        description: "容器 App 發布時找不到 compose.yaml 定義檔。",
+        suggestion: "請在專案根目錄補上 compose.yaml。",
+    },
+    CURATED_COMPOSE_GATE_FAILED: {
+        code: "CURATED_COMPOSE_GATE_FAILED",
+        description: "Compose 未通過 Curated CI 嚴格門檻（如映像檔必須帶 immutable sha256 digest）。",
+        suggestion: "請在 compose.yaml 使用固定 digest 的公開 OCI 映像檔（image@sha256:...），並移除 build 區塊。",
+    },
+    CURATED_COMPOSE_BUILD_FORBIDDEN: {
+        code: "CURATED_COMPOSE_BUILD_FORBIDDEN",
+        description: "Curated 發布禁止使用 compose build: 區塊。",
+        suggestion: "請移除 compose.yaml 中的 build: 區塊，並指定已發布至公開 registry 的 image。",
+    },
+    CURATED_COMPOSE_IMAGE_REQUIRED: {
+        code: "CURATED_COMPOSE_IMAGE_REQUIRED",
+        description: "Curated 服務必須宣告 image 映像檔名稱。",
+        suggestion: "請在 compose.yaml 的 service 中宣告 image: 欄位。",
+    },
+    CURATED_COMPOSE_IMAGE_DIGEST_REQUIRED: {
+        code: "CURATED_COMPOSE_IMAGE_DIGEST_REQUIRED",
+        description: "Curated 映像檔必須使用不可變的 @sha256: 摘要鎖定。",
+        suggestion: "請在 image 加上不可變的 SHA-256 Digest（例如 image: redis@sha256:...）。",
+    },
+    CURATED_COMPOSE_SERVICES_REQUIRED: {
+        code: "CURATED_COMPOSE_SERVICES_REQUIRED",
+        description: "compose.yaml 缺少 services 區塊或服務為空。",
+        suggestion: "請在 compose.yaml 至少定義一個容器服務。",
+    },
+    CURATED_BUNDLE_FILE_MISSING: {
+        code: "CURATED_BUNDLE_FILE_MISSING",
+        description: "打包 Curated Release 時缺少必要的 Bundle 檔案。",
+        suggestion: "請確認專案根目錄包含完整的 synology-app.yaml 與 compose.yaml/native.yaml。",
+    },
+    CURATED_ATTESTATION_BINDING_FAILED: {
+        code: "CURATED_ATTESTATION_BINDING_FAILED",
+        description: "Curated Attestation Token 簽署或綁定聲明失敗。",
+        suggestion: "請檢查 signing keys 與 claims 內容。",
+    },
+    CURATED_ATTESTATION_SIGNATURE_INVALID: {
+        code: "CURATED_ATTESTATION_SIGNATURE_INVALID",
+        description: "Curated Attestation JWT 簽章無效。",
+        suggestion: "請確認簽署私鑰與公開信任根 Keyring 一致。",
+    },
+    CURATED_BUILD_FAILED: {
+        code: "CURATED_BUILD_FAILED",
+        description: "建置 Curated SPK 失敗。",
+        suggestion: "請檢查建置日誌以排除檔案或權限錯誤。",
+    },
+    CURATED_RELEASE_ATTESTATION_BINDING_FAILED: {
+        code: "CURATED_RELEASE_ATTESTATION_BINDING_FAILED",
+        description: "Detached Release Attestation 綁定 SPK 雜湊失敗。",
+        suggestion: "請確保產出的 SPK 位元組雜湊與簽署聲明一致。",
+    },
+    CURATED_EMBEDDED_ATTESTATION_MISSING: {
+        code: "CURATED_EMBEDDED_ATTESTATION_MISSING",
+        description: "已建置的 Curated SPK 內缺少嵌入的 Attestation Token。",
+        suggestion: "請檢查 build-spk 是否正確將 token 寫入 package/.synopkgland/token。",
+    },
+    CURATED_EMBEDDED_ATTESTATION_BINDING_FAILED: {
+        code: "CURATED_EMBEDDED_ATTESTATION_BINDING_FAILED",
+        description: "SPK 內嵌入的 Attestation 與 Release Claims 聲明不符。",
+        suggestion: "請確認嵌入式 Token 的 Digest 與 Claims 一致。",
+    },
+    // --- Publish & Preflight ---
+    PREFLIGHT_FAILED: {
+        code: "PREFLIGHT_FAILED",
+        description: "送審公開發布前置檢查未通過。",
+        suggestion: "請先修正 preflight 列出的錯誤後再重新送審。",
+    },
+    COMMUNITY_APPS_ROOT_MISSING: {
+        code: "COMMUNITY_APPS_ROOT_MISSING",
+        description: "找不到 synopkgland-community-apps 本機副本。",
+        suggestion: "請 clone synopkgland-community-apps 並設定 SYNOPKGLAND_COMMUNITY_APPS_ROOT 環境變數。",
+    },
+    PACKAGE_IDENTITY_MISSING: {
+        code: "PACKAGE_IDENTITY_MISSING",
+        description: "專案 synology-app.yaml 中缺少 package 欄位。",
+        suggestion: "請在 synology-app.yaml 補上 package 宣告。",
+    },
+    PACKAGE_DIRECTORY_MISMATCH: {
+        code: "PACKAGE_DIRECTORY_MISMATCH",
+        description: "專案目錄或 Community Apps 子目錄與 package 名稱不一致。",
+        suggestion: "請確保專案目錄名稱與 package 宣告一致。",
+    },
+    PUBLISH_SOURCE_IS_COMMUNITY_APP: {
+        code: "PUBLISH_SOURCE_IS_COMMUNITY_APP",
+        description: "publish 指令不可在 synopkgland-community-apps/apps 目錄內直接執行。",
+        suggestion: "請在您的獨立 App 開發專案目錄中執行 public-release-submit。",
+    },
+    PUBLISH_PR_FAILED: {
+        code: "PUBLISH_PR_FAILED",
+        description: "透過 GitHub CLI 建立 Pull Request 失敗。",
+        suggestion: "請確認 gh 已登入 (gh auth login) 或已設定 GITHUB_TOKEN。",
+    },
+};
+export function getErrorCode(code) {
+    return ERROR_REGISTRY[code];
+}