@synopackageland/cli 0.3.1 → 0.3.2

package/dist/doctor.js

@@ -0,0 +1,594 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { validateProject } from "./validate.js";
+import { resolveDeployIdentity } from "./deploy/identity.js";
+import { loadContract } from "./contract/load.js";
+import { getErrorCode } from "./error-registry.js";
+import { dsmFetch } from "./host/dsm-http.js";
+import { appOriginFromContract } from "./host/open-url.js";
+const PROJECT_FOUR_FILES = ["synology-app.yaml", "README.md", "icon.png"];
+function packageFailureSummary(state) {
+    const fields = [];
+    if (state.error?.code !== undefined) {
+        fields.push(`error.code=${state.error.code}`);
+    }
+    if (state.error?.description) {
+        fields.push(`description=${state.error.description}`);
+    }
+    if (state.brokenBy) {
+        fields.push(`broken_by=${state.brokenBy}`);
+    }
+    if (state.stage) {
+        fields.push(`stage=${state.stage}`);
+    }
+    if (state.lastStage) {
+        fields.push(`last_stage=${state.lastStage}`);
+    }
+    if (state.statusCode !== undefined) {
+        fields.push(`statusCode=${state.statusCode}`);
+    }
+    if (state.statusDescription) {
+        fields.push(`statusDescription=${state.statusDescription}`);
+    }
+    if (state.statusOrigin) {
+        fields.push(`statusOrigin=${state.statusOrigin}`);
+    }
+    if (state.error?.code === undefined && !state.error?.description && !state.stage) {
+        fields.push("event.error/stage 未由 Package API 回傳");
+    }
+    if (fields.length === 0) {
+        return "DSM API 未回傳可用的失敗欄位";
+    }
+    return `DSM 回報：${fields.join("；")}`;
+}
+function packageFailureSuggestion(state) {
+    const diagnosis = state.error?.code === 276
+        ? "DSM error 276（postinst worker acquire 失敗）常見原因是 Compose command 含純數字元素，或發布的 port 已被占用；請把數字參數併入 flag／用 sh -c 包成單一字串，並確認 host port 未被其他服務使用。"
+        : state.error?.code === undefined &&
+            state.statusCode === 150 &&
+            state.brokenBy === "install_corruption"
+            ? "DSM Package API 未回傳 event error.code；同類 install_corruption/status 150 的實機 event 曾對應 error 276。常見原因是 Compose command 含純數字元素，或發布的 port 已被占用；請把數字參數併入 flag／用 sh -c 包成單一字串，並確認 host port 未被其他服務使用。"
+            : "請依 DSM 回報的欄位檢查 Package Center 安裝流程與 Compose 設定，必要時重新安裝套件。";
+    const workerMessage = state.error?.workerMsg && state.error.workerMsg.length > 0
+        ? `DSM API 已提供 ${state.error.workerMsg.length} 筆 worker_msg；`
+        : "DSM API 的 worker_msg 實測為空或未提供；";
+    return `${diagnosis} ${workerMessage}worker 內部完整訊息只存在 NAS 的 /var/log/synoplugin.log（需 root），doctor 不會假裝取得。`;
+}
+export async function runDoctor(options) {
+    const checks = [];
+    // --- 1. Local checks (Always run) ---
+    if (!options.project) {
+        const errorEntry = getErrorCode("PROJECT_FILES_MISSING");
+        checks.push({
+            id: "project.files",
+            status: "fail",
+            code: "PROJECT_FILES_MISSING",
+            message: "找不到 synology-app.yaml。請在專案根目錄執行，或使用 --project 指定。",
+            suggestion: errorEntry?.suggestion ?? "請在 App 專案根目錄執行 doctor，或使用 synopkgland init 建立專案。",
+        });
+        checks.push({
+            id: "project.validate",
+            status: "skip",
+            message: "專案不存在，略過合約與 Compose 靜態驗證",
+        });
+    }
+    else {
+        const project = options.project;
+        // Check 1.1: Project four files
+        // In a Compose project: synology-app.yaml, compose.yaml
+        // In a Native project: synology-app.yaml, native.yaml
+        // Additional packaging files (README.md, icon.png) are checked as well.
+        const missingFiles = [];
+        if (!existsSync(project.contractPath)) {
+            missingFiles.push("synology-app.yaml");
+        }
+        const hasCompose = existsSync(project.composePath);
+        const hasNative = existsSync(project.nativePath ?? join(project.root, "native.yaml"));
+        if (!hasCompose && !hasNative) {
+            missingFiles.push("compose.yaml 或 native.yaml");
+        }
+        if (missingFiles.length > 0) {
+            const errorEntry = getErrorCode("PROJECT_FILES_MISSING");
+            checks.push({
+                id: "project.files",
+                status: "fail",
+                code: "PROJECT_FILES_MISSING",
+                message: `專案缺少核心定義檔案：${missingFiles.join(", ")}`,
+                suggestion: errorEntry?.suggestion ?? "請補齊缺失的專案核心檔案。",
+            });
+        }
+        else {
+            const packagingNotice = ["README.md", "icon.png"].filter((f) => !existsSync(join(project.root, f)));
+            const detail = packagingNotice.length > 0 ? `（公開發布建議補齊 ${packagingNotice.join(", ")}）` : "";
+            checks.push({
+                id: "project.files",
+                status: "pass",
+                message: `專案核心定義檔案皆存在${detail}`,
+            });
+        }
+        // Check 1.2: Contract / Compose / Native validation (reuses analyzer)
+        const validation = validateProject(project, { profile: "personal" });
+        if (!validation.ok) {
+            const firstError = validation.errors[0];
+            const code = firstError?.code ?? "VALIDATION_FAILED";
+            const errorEntry = getErrorCode(code);
+            checks.push({
+                id: "project.validate",
+                status: "fail",
+                code,
+                message: firstError ? `${firstError.message}` : "專案合約或 Compose 驗證失敗",
+                suggestion: firstError?.suggestion ?? errorEntry?.suggestion ?? "請執行 synopkgland validate 修正錯誤。",
+            });
+        }
+        else {
+            checks.push({
+                id: "project.validate",
+                status: "pass",
+                message: "合約與 Compose / Native 靜態驗證通過",
+            });
+        }
+    }
+    // Check 1.3: CLI toolchain version drift
+    let cliVersion = "unknown";
+    try {
+        const pkgJsonPath = new URL("../package.json", import.meta.url);
+        const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+        cliVersion = pkg.version ?? "unknown";
+    }
+    catch {
+        // ignore
+    }
+    let toolchainVersion;
+    const projectRoot = options.project ? options.project.root : process.cwd();
+    const toolchainScriptPath = join(projectRoot, "..", "ci", "standalone-toolchain.sh");
+    if (existsSync(toolchainScriptPath)) {
+        try {
+            const script = readFileSync(toolchainScriptPath, "utf8");
+            const match = /TOOLCHAIN_VERSION="([^"]+)"/.exec(script);
+            if (match?.[1]) {
+                toolchainVersion = match[1];
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (toolchainVersion && cliVersion !== "unknown" && cliVersion !== toolchainVersion) {
+        const errorEntry = getErrorCode("CLI_VERSION_DRIFT");
+        checks.push({
+            id: "cli.version",
+            status: "fail",
+            code: "CLI_VERSION_DRIFT",
+            message: `CLI 版本 (${cliVersion}) 與 CI TOOLCHAIN_VERSION (${toolchainVersion}) 不一致`,
+            suggestion: errorEntry?.suggestion ?? "請更新 CLI 或 CI 設定使版本一致。",
+        });
+    }
+    else {
+        checks.push({
+            id: "cli.version",
+            status: "pass",
+            message: `CLI 版本 (${cliVersion}) 正常`,
+        });
+    }
+    // --- 2. Host checks ---
+    if (!options.host) {
+        checks.push({
+            id: "host.reachability",
+            status: "skip",
+            message: "未指定 --host，略過 NAS 檢查",
+        });
+        checks.push({
+            id: "host.broker",
+            status: "skip",
+            message: "未指定 --host，略過 Broker 檢查",
+        });
+        checks.push({
+            id: "host.attestation_trust_root",
+            status: "skip",
+            message: "未指定 --host，略過 Attestation Trust Root 檢查",
+        });
+        if (options.packageId) {
+            checks.push({
+                id: "host.package_binding",
+                status: "skip",
+                message: "未指定 --host，略過 Package Binding 檢查",
+            });
+            checks.push({
+                id: "host.trusted_app_entry",
+                status: "skip",
+                message: "未指定 --host，略過 Trusted App Entry 檢查",
+            });
+        }
+    }
+    else {
+        const host = options.host;
+        // Check 2.1: NAS Reachability
+        let isReachable = false;
+        try {
+            // Use getInstalledPackageVersion probe or fetch
+            await host.isPackageInstalled("SynoPkgLandService");
+            isReachable = true;
+            checks.push({
+                id: "host.reachability",
+                status: "pass",
+                message: `成功連線至 NAS (${host.dsmOrigin})`,
+            });
+        }
+        catch (error) {
+            const errorEntry = getErrorCode("HOST_UNREACHABLE");
+            const errStr = error instanceof Error ? error.message : String(error);
+            const isNodeUnreach = errStr.includes("EHOSTUNREACH") || errStr.includes("ENETUNREACH");
+            const suggestion = isNodeUnreach
+                ? "連線失敗 (EHOSTUNREACH)。已內建 curl fallback，請確認 NAS IP/網址可達且防火牆允許連線。"
+                : (errorEntry?.suggestion ?? "請檢查 NAS 位址與憑證。");
+            checks.push({
+                id: "host.reachability",
+                status: "fail",
+                code: "HOST_UNREACHABLE",
+                message: `無法連線至 NAS (${host.dsmOrigin})：${errStr}`,
+                suggestion,
+            });
+        }
+        if (!isReachable) {
+            checks.push({
+                id: "host.broker",
+                status: "skip",
+                message: "NAS 無法連線，略過 Broker 檢查",
+            });
+            checks.push({
+                id: "host.attestation_trust_root",
+                status: "skip",
+                message: "NAS 無法連線，略過 Attestation Trust Root 檢查",
+            });
+            if (options.packageId) {
+                checks.push({
+                    id: "host.package_binding",
+                    status: "skip",
+                    message: "NAS 無法連線，略過 Package Binding 檢查",
+                });
+                checks.push({
+                    id: "host.trusted_app_entry",
+                    status: "skip",
+                    message: "NAS 無法連線，略過 Trusted App Entry 檢查",
+                });
+            }
+        }
+        else {
+            // Check 2.2: Broker installed / running
+            let isBrokerReady = false;
+            let brokerInstalled;
+            try {
+                brokerInstalled = await host.isPackageInstalled("SynoPkgLandService");
+                if (!brokerInstalled) {
+                    const errorEntry = getErrorCode("BROKER_NOT_INSTALLED");
+                    checks.push({
+                        id: "host.broker",
+                        status: "fail",
+                        code: "BROKER_NOT_INSTALLED",
+                        message: "目標 NAS 尚未安裝 SynoPkgLandService (Broker)",
+                        suggestion: errorEntry?.suggestion ?? "請至 DSM Package Center 安裝 SynoPkgLandService 套件。",
+                    });
+                }
+                else {
+                    // Probe inner-loop API
+                    try {
+                        await host.getAttestationInfo("probe");
+                        isBrokerReady = true;
+                        checks.push({
+                            id: "host.broker",
+                            status: "pass",
+                            message: "SynoPkgLandService (Broker) 已安裝且運作中",
+                        });
+                    }
+                    catch (innerErr) {
+                        const errCode = innerErr?.code;
+                        if (errCode === "INNER_LOOP_API_MISSING") {
+                            const errorEntry = getErrorCode("INNER_LOOP_API_MISSING");
+                            checks.push({
+                                id: "host.broker",
+                                status: "fail",
+                                code: "INNER_LOOP_API_MISSING",
+                                message: "Broker inner-loop API 不可用，版本可能過舊",
+                                suggestion: errorEntry?.suggestion ?? "請升級 SynoPkgLandService 套件至最新版本。",
+                            });
+                        }
+                        else {
+                            isBrokerReady = true;
+                            checks.push({
+                                id: "host.broker",
+                                status: "pass",
+                                message: "SynoPkgLandService (Broker) 運作中",
+                            });
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                const errorEntry = getErrorCode("BROKER_NOT_INSTALLED");
+                checks.push({
+                    id: "host.broker",
+                    status: "fail",
+                    code: "BROKER_NOT_INSTALLED",
+                    message: `Broker 狀態檢查失敗：${err instanceof Error ? err.message : String(err)}`,
+                    suggestion: errorEntry?.suggestion ?? "請確認 SynoPkgLandService 已安裝並正常啟動。",
+                });
+            }
+            // Check 2.3: Attestation Trust Root
+            if (!isBrokerReady) {
+                checks.push({
+                    id: "host.attestation_trust_root",
+                    status: "skip",
+                    message: "Broker 未就緒，略過 Trust Root 檢查",
+                });
+            }
+            else {
+                // Probe trust root availability
+                try {
+                    const info = await host.getAttestationInfo("probe");
+                    if (info.attestationKind === "none") {
+                        // Not broken, trust root is fine or absent
+                        checks.push({
+                            id: "host.attestation_trust_root",
+                            status: "pass",
+                            message: "Broker Attestation API 已連通",
+                        });
+                    }
+                    else {
+                        checks.push({
+                            id: "host.attestation_trust_root",
+                            status: "pass",
+                            message: "Broker Attestation API 已連通",
+                        });
+                    }
+                }
+                catch (attErr) {
+                    const errCode = attErr?.code;
+                    if (errCode === "ATTESTATION_TRUST_ROOT_MISSING") {
+                        const errorEntry = getErrorCode("ATTESTATION_TRUST_ROOT_MISSING");
+                        checks.push({
+                            id: "host.attestation_trust_root",
+                            status: "fail",
+                            code: "ATTESTATION_TRUST_ROOT_MISSING",
+                            message: "Broker 缺少生產環境 Attestation Trust Root 信任根憑證",
+                            suggestion: errorEntry?.suggestion ?? "請確認 SynoPkgLandService 套件完整安裝且 trust root keyring 未被移除。",
+                        });
+                    }
+                    else if (errCode === "ATTESTATION_MISSING") {
+                        const errorEntry = getErrorCode("ATTESTATION_MISSING");
+                        checks.push({
+                            id: "host.attestation_trust_root",
+                            status: "fail",
+                            code: "ATTESTATION_MISSING",
+                            message: "App Bundle 缺少必要的 Attestation 簽章憑證",
+                            suggestion: errorEntry?.suggestion ?? "請先透過 synopkgland deploy 簽發 Local Attestation。",
+                        });
+                    }
+                    else if (errCode === "ATTESTATION_INVALID") {
+                        const errorEntry = getErrorCode("ATTESTATION_INVALID");
+                        checks.push({
+                            id: "host.attestation_trust_root",
+                            status: "fail",
+                            code: "ATTESTATION_INVALID",
+                            message: "Attestation Token 驗證失敗",
+                            suggestion: errorEntry?.suggestion ?? "請重新執行 synopkgland deploy 產生新 Attestation。",
+                        });
+                    }
+                    else {
+                        checks.push({
+                            id: "host.attestation_trust_root",
+                            status: "pass",
+                            message: "Broker Attestation API 已連通",
+                        });
+                    }
+                }
+            }
+            // Check 2.4: If packageId is provided (or derived)
+            const targetPackageId = options.packageId ?? (options.project ? resolveDeployIdentity(options.project, { dev: options.dev }).packageId : undefined);
+            if (targetPackageId) {
+                if (brokerInstalled === false) {
+                    checks.push({
+                        id: "host.package_binding",
+                        status: "skip",
+                        message: `Broker 未安裝，無法查詢套件 ${targetPackageId} 的 Project Binding`,
+                    });
+                    checks.push({
+                        id: "host.trusted_app_entry",
+                        status: "skip",
+                        message: `Broker 未安裝，略過套件 ${targetPackageId} 的 Trusted App Entry 探測`,
+                    });
+                }
+                else {
+                    try {
+                        const isInstalled = await host.isPackageInstalled(targetPackageId);
+                        if (!isInstalled) {
+                            checks.push({
+                                id: "host.package_binding",
+                                status: "skip",
+                                message: `套件 ${targetPackageId} 尚未部署至此 NAS`,
+                            });
+                            checks.push({
+                                id: "host.trusted_app_entry",
+                                status: "skip",
+                                message: `套件 ${targetPackageId} 未安裝，略過 Web Entry 探測`,
+                            });
+                        }
+                        else {
+                            // Check DSM package status first
+                            let dsmPackageState;
+                            if (host.getInstalledPackageState) {
+                                try {
+                                    dsmPackageState = await host.getInstalledPackageState(targetPackageId);
+                                }
+                                catch {
+                                    // ignore
+                                }
+                            }
+                            const isBroken = dsmPackageState?.status !== undefined &&
+                                /(broken|error|fail|installing|150)/i.test(dsmPackageState.status);
+                            if (isBroken && dsmPackageState) {
+                                checks.push({
+                                    id: "host.package_binding",
+                                    status: "fail",
+                                    code: "PACKAGE_BROKEN",
+                                    message: `套件 ${targetPackageId} 在 DSM 處於異常狀態（status: ${dsmPackageState.status}）。${packageFailureSummary(dsmPackageState)}`,
+                                    suggestion: packageFailureSuggestion(dsmPackageState),
+                                });
+                                checks.push({
+                                    id: "host.trusted_app_entry",
+                                    status: "skip",
+                                    message: `套件 ${targetPackageId} 安裝異常，略過 Web Entry 探測`,
+                                });
+                            }
+                            else {
+                                const info = await host.getAttestationInfo(targetPackageId);
+                                if (info.readiness === "NOT_INSTALLED") {
+                                    const errorEntry = getErrorCode("PROJECT_BINDING_NOT_FOUND");
+                                    checks.push({
+                                        id: "host.package_binding",
+                                        status: "fail",
+                                        code: "PROJECT_BINDING_NOT_FOUND",
+                                        message: `套件 ${targetPackageId} 在 Broker 中無有效 Project Binding`,
+                                        suggestion: errorEntry?.suggestion ?? "請執行 synopkgland deploy 重新部署套件。",
+                                    });
+                                }
+                                else if (info.readiness === "PROJECT_BINDING_DRIFTED") {
+                                    const errorEntry = getErrorCode("PROJECT_BINDING_DRIFTED");
+                                    checks.push({
+                                        id: "host.package_binding",
+                                        status: "fail",
+                                        code: "PROJECT_BINDING_DRIFTED",
+                                        message: `套件 ${targetPackageId} Project Binding 發生狀態漂移`,
+                                        suggestion: errorEntry?.suggestion ?? "請執行 synopkgland deploy 重新同步部署。",
+                                    });
+                                }
+                                else if (info.readiness === "PROJECT_BINDING_REMOVED") {
+                                    const errorEntry = getErrorCode("PROJECT_BINDING_REMOVED");
+                                    checks.push({
+                                        id: "host.package_binding",
+                                        status: "fail",
+                                        code: "PROJECT_BINDING_REMOVED",
+                                        message: `套件 ${targetPackageId} Project Binding 已被標記為移除`,
+                                        suggestion: errorEntry?.suggestion ?? "請重新安裝套件。",
+                                    });
+                                }
+                                else if (info.readiness === "PROJECT_BINDING_UNKNOWN") {
+                                    const errorEntry = getErrorCode("PROJECT_BINDING_UNKNOWN");
+                                    checks.push({
+                                        id: "host.package_binding",
+                                        status: "fail",
+                                        code: "PROJECT_BINDING_UNKNOWN",
+                                        message: `套件 ${targetPackageId} Project 狀態暫時無法取得`,
+                                        suggestion: errorEntry?.suggestion ?? "請至 DSM 確認 Container Manager 服務正常運作。",
+                                    });
+                                }
+                                else if (info.readiness === "READINESS_TIMEOUT") {
+                                    const errorEntry = getErrorCode("READINESS_TIMEOUT");
+                                    checks.push({
+                                        id: "host.package_binding",
+                                        status: "fail",
+                                        code: "READINESS_TIMEOUT",
+                                        message: `套件 ${targetPackageId} 啟動逾時`,
+                                        suggestion: errorEntry?.suggestion ?? "請使用 synopkgland log --host <nas> 檢查容器啟動日誌。",
+                                    });
+                                }
+                                else {
+                                    const attNotice = info.attestationKind === "none" ? "未綁定 Attestation" : `Attestation：${info.attestationKind}`;
+                                    checks.push({
+                                        id: "host.package_binding",
+                                        status: "pass",
+                                        message: `Project Binding 正常（狀態：${info.readiness ?? "RUNNING"}，${attNotice}）`,
+                                    });
+                                }
+                                // Resource-worker SPKs do not register with Broker, so their
+                                // Broker info has no openUrl even though the generated package
+                                // still declares a Web entry. Keep the same contract fallback
+                                // used by `info` and bind it to the explicitly diagnosed ID.
+                                const contract = options.project
+                                    ? loadContract(options.project.contractPath).contract
+                                    : undefined;
+                                const contractOpenUrl = contract
+                                    ? appOriginFromContract(host.dsmOrigin, {
+                                        package: targetPackageId,
+                                        adminprotocol: contract.adminprotocol,
+                                        adminport: contract.adminport,
+                                    })
+                                    : undefined;
+                                const openUrl = info.openUrl ?? contractOpenUrl;
+                                const hasDeclaredWebEntry = contract?.adminport !== undefined &&
+                                    contract.adminport !== null &&
+                                    contract.adminport !== "";
+                                // HTTP probe on Trusted App Entry if an Open URL exists.
+                                if (openUrl) {
+                                    try {
+                                        const response = await dsmFetch(openUrl);
+                                        if (response.ok) {
+                                            checks.push({
+                                                id: "host.trusted_app_entry",
+                                                status: "pass",
+                                                message: `Trusted App Entry 存取正常 (HTTP ${response.status})：${openUrl}`,
+                                            });
+                                        }
+                                        else {
+                                            const errorEntry = getErrorCode("TRUSTED_APP_ENTRY_FAILED");
+                                            checks.push({
+                                                id: "host.trusted_app_entry",
+                                                status: "fail",
+                                                code: "TRUSTED_APP_ENTRY_FAILED",
+                                                message: `Trusted App Entry HTTP 探測回傳 ${response.status}（可能為 WEBSTATION_ENTRY_FAILED）：${openUrl}`,
+                                                suggestion: errorEntry?.suggestion ?? "請至 DSM Web Station 檢查反向代理與容器連接埠。",
+                                            });
+                                        }
+                                    }
+                                    catch (httpErr) {
+                                        const errorEntry = getErrorCode("TRUSTED_APP_ENTRY_FAILED");
+                                        checks.push({
+                                            id: "host.trusted_app_entry",
+                                            status: "fail",
+                                            code: "TRUSTED_APP_ENTRY_FAILED",
+                                            message: `無法連線至 Trusted App Entry (${openUrl})：${httpErr instanceof Error ? httpErr.message : String(httpErr)}`,
+                                            suggestion: errorEntry?.suggestion ?? "請檢查容器內部 Web 服務是否正常監聽並啟動。",
+                                        });
+                                    }
+                                }
+                                else {
+                                    checks.push({
+                                        id: "host.trusted_app_entry",
+                                        status: "skip",
+                                        message: hasDeclaredWebEntry
+                                            ? "此套件已宣告 Web 入口，但無法取得 Trusted App Entry Open URL，略過探測"
+                                            : options.project
+                                                ? "此套件沒有 Web 入口（Headless App），略過 Trusted App Entry 探測"
+                                                : "無法取得此套件的 Trusted App Entry Open URL，略過探測",
+                                    });
+                                }
+                            }
+                        }
+                    }
+                    catch (pkgErr) {
+                        checks.push({
+                            id: "host.package_binding",
+                            status: "skip",
+                            message: `查詢套件 ${targetPackageId} 狀態失敗：${pkgErr instanceof Error ? pkgErr.message : String(pkgErr)}`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    const ok = checks.every((c) => c.status !== "fail");
+    return { ok, checks };
+}
+export function formatDoctorReport(report) {
+    const lines = [];
+    for (const check of report.checks) {
+        const symbol = check.status === "pass" ? "[✓]" : check.status === "fail" ? "[✗]" : "[-]";
+        const codeTag = check.code ? ` [${check.code}]` : "";
+        lines.push(`${symbol} ${check.id}${codeTag}: ${check.message}`);
+        if (check.status === "fail" && check.suggestion) {
+            lines.push(`    建議：${check.suggestion}`);
+        }
+    }
+    lines.push("");
+    lines.push(report.ok ? "診斷全部通過。" : "診斷發現問題，請依照上述建議修正。");
+    return lines.join("\n");
+}

package/dist/error-collector.d.ts

@@ -0,0 +1,2 @@
+export declare function extractReferencedErrorCodes(srcDirectory: string): Set<string>;
+export declare function extractAllStringLiterals(srcDirectory: string): Set<string>;

package/dist/error-collector.js

@@ -0,0 +1,46 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { ERROR_REGISTRY } from "../src/error-registry.js";
+function getAllTsFiles(dir, excludeDirs = []) {
+    const files = [];
+    for (const entry of readdirSync(dir)) {
+        const fullPath = join(dir, entry);
+        if (statSync(fullPath).isDirectory()) {
+            if (!excludeDirs.includes(entry)) {
+                files.push(...getAllTsFiles(fullPath, excludeDirs));
+            }
+        }
+        else if (fullPath.endsWith(".ts")) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+export function extractReferencedErrorCodes(srcDirectory) {
+    const tsFiles = getAllTsFiles(srcDirectory, ["mock-broker"]).filter((f) => !f.endsWith("error-registry.ts"));
+    const referenced = new Set();
+    for (const file of tsFiles) {
+        const content = readFileSync(file, "utf8");
+        for (const code of Object.keys(ERROR_REGISTRY)) {
+            // Check if `code` appears as a string literal or identifier in the file
+            if (content.includes(`"${code}"`) || content.includes(`'${code}'`) || content.includes(`\`${code}\``)) {
+                referenced.add(code);
+            }
+        }
+    }
+    return referenced;
+}
+export function extractAllStringLiterals(srcDirectory) {
+    const tsFiles = getAllTsFiles(srcDirectory, ["mock-broker"]).filter((f) => !f.endsWith("error-registry.ts"));
+    const literals = new Set();
+    const codeRegex = /["']([A-Z][A-Z0-9_]{2,})["']/g;
+    for (const file of tsFiles) {
+        const content = readFileSync(file, "utf8");
+        codeRegex.lastIndex = 0;
+        let match;
+        while ((match = codeRegex.exec(content)) !== null) {
+            literals.add(match[1]);
+        }
+    }
+    return literals;
+}

package/dist/error-registry.d.ts

@@ -0,0 +1,7 @@
+export interface ErrorCodeEntry {
+    code: string;
+    description: string;
+    suggestion: string;
+}
+export declare const ERROR_REGISTRY: Record<string, ErrorCodeEntry>;
+export declare function getErrorCode(code: string): ErrorCodeEntry | undefined;