@synopackageland/cli 0.3.10 → 0.4.1

package/dist/doctor.js

@@ -1,822 +0,0 @@
-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";
-import { DSM_PORT_PROFILE_PRECISION_WARNING, } from "./host/dsm-port-profile.js";
-function packageRouteFromDiagnostics(diagnostics) {
-    switch (diagnostics?.packageRoute) {
-        case "package-only":
-        case "broker-installer":
-        case "unknown":
-            return diagnostics.packageRoute;
-        default:
-            break;
-    }
-    // Keep compatibility with the boolean-only response emitted by older
-    // Brokers, but never infer broker-installer from missing evidence.
-    return diagnostics?.isPackageOnly === true ? "package-only" : "unknown";
-}
-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 不會假裝取得。`;
-}
-function formatDsmPortProfile(profile) {
-    const ports = profile.dstPorts
-        .map((range) => range.start === range.end ? String(range.start) : `${range.start}-${range.end}`)
-        .join(",");
-    return `${profile.containerName} (project ${profile.projectName}, port ${ports})`;
-}
-function formatDsmPortProfiles(profiles) {
-    return profiles.map(formatDsmPortProfile).join("；");
-}
-function brokerPortProfileNames(residue) {
-    return new Set((residue?.items ?? [])
-        .filter((item) => item.kind === "port_profile_sc")
-        .map((item) => item.name));
-}
-async function appendDsmPortProfileCheck(checks, host, options) {
-    // The API fallback is authoritative only when the Broker is absent. An
-    // installed-but-unready Broker has no trustworthy residue conclusion, so do
-    // not silently substitute a lower-precision result for it.
-    if (!options.brokerReady && options.brokerInstalled !== false) {
-        checks.push({
-            id: "host.dsm_port_profile",
-            status: "skip",
-            message: "Broker 未就緒，略過 DSM PortInfo port profile 盤點",
-        });
-        return;
-    }
-    if (!host.getDsmPortProfileInventory) {
-        checks.push({
-            id: "host.dsm_port_profile",
-            status: "skip",
-            message: "DSM PortInfo API 能力不可用，略過 port profile 盤點",
-        });
-        return;
-    }
-    let inventory;
-    try {
-        inventory = await host.getDsmPortProfileInventory();
-    }
-    catch {
-        inventory = undefined;
-    }
-    if (!inventory) {
-        checks.push({
-            id: "host.dsm_port_profile",
-            status: "skip",
-            message: "DSM PortInfo API 或已安裝套件清單無法取得，略過 port profile 盤點",
-        });
-        return;
-    }
-    if (options.brokerReady) {
-        const apiNames = new Set(inventory.orphaned.map((profile) => profile.containerName));
-        const brokerNames = brokerPortProfileNames(options.brokerResidue);
-        const agrees = options.brokerResidue !== undefined &&
-            apiNames.size === brokerNames.size &&
-            [...apiNames].every((name) => brokerNames.has(name));
-        if (agrees) {
-            checks.push({
-                id: "host.dsm_port_profile",
-                status: "pass",
-                message: `DSM PortInfo API 交叉檢查與 Broker 的 port profile 結果一致（${apiNames.size} 筆；Broker 判定優先）`,
-            });
-        }
-        else {
-            const apiDetail = inventory.orphaned.length > 0
-                ? `API 候選 ${inventory.orphaned.length} 筆：${formatDsmPortProfiles(inventory.orphaned)}`
-                : "API 未發現候選";
-            checks.push({
-                id: "host.dsm_port_profile",
-                status: "skip",
-                message: `DSM PortInfo API 交叉檢查${apiDetail}；Broker 判定優先，未覆蓋 host.dsm_residue（${DSM_PORT_PROFILE_PRECISION_WARNING}）`,
-            });
-        }
-        return;
-    }
-    // No Broker: this is the primary result, but explicitly expose the one
-    // precision gap that the administrator session cannot close.
-    if (inventory.orphaned.length > 0) {
-        checks.push({
-            id: "host.dsm_port_profile",
-            status: "warn",
-            message: `發現 ${inventory.orphaned.length} 筆 DSM port profile 疑似孤兒（${DSM_PORT_PROFILE_PRECISION_WARNING}）：${formatDsmPortProfiles(inventory.orphaned)}`,
-            suggestion: "這是未經 conf/resource 交叉比對的 API 候選；請先人工確認 Compose project 名，再由管理員清理。",
-        });
-    }
-    else {
-        checks.push({
-            id: "host.dsm_port_profile",
-            status: "pass",
-            message: `無 DSM port profile 孤兒候選（${DSM_PORT_PROFILE_PRECISION_WARNING}）`,
-        });
-    }
-}
-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 檢查",
-            });
-        }
-        checks.push({
-            id: "host.oidc_origin",
-            status: "skip",
-            message: "未指定 --host，略過 OIDC origin 檢查",
-        });
-    }
-    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 檢查",
-            });
-            checks.push({
-                id: "host.oidc_origin",
-                status: "skip",
-                message: "NAS 無法連線，略過 OIDC origin 檢查",
-            });
-            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.3a: OIDC-compatible public origin. This is deliberately
-            // optional so a pre-A39 Broker remains a usable doctor target.
-            if (!isBrokerReady || !host.getOidcCompatSettings) {
-                checks.push({
-                    id: "host.oidc_origin",
-                    status: "skip",
-                    message: !isBrokerReady
-                        ? "Broker 未就緒，略過 OIDC origin 檢查"
-                        : "舊版 Broker 沒有 OIDC origin endpoint，略過",
-                });
-            }
-            else {
-                try {
-                    const oidc = await host.getOidcCompatSettings();
-                    if (!oidc) {
-                        checks.push({
-                            id: "host.oidc_origin",
-                            status: "skip",
-                            message: "舊版 Broker 沒有 OIDC origin endpoint，略過",
-                        });
-                    }
-                    else if (oidc.origin.ready && oidc.origin.hostname) {
-                        checks.push({
-                            id: "host.oidc_origin",
-                            status: "pass",
-                            message: `${oidc.origin.kind} ${oidc.origin.hostname}`,
-                        });
-                    }
-                    else {
-                        checks.push({
-                            id: "host.oidc_origin",
-                            status: "skip",
-                            message: `未就緒（${oidc.origin.kind}）：${oidc.origin.setupHint}`,
-                        });
-                    }
-                }
-                catch {
-                    checks.push({
-                        id: "host.oidc_origin",
-                        status: "skip",
-                        message: "OIDC origin endpoint 無法取得，略過",
-                    });
-                }
-            }
-            // Check 2.3b: DSM Residue check (A29)
-            let brokerResidue;
-            if (isBrokerReady && host.getDsmDiagnostics) {
-                try {
-                    const diag = await host.getDsmDiagnostics("probe");
-                    if (diag && diag.dsmResidue) {
-                        const residue = diag.dsmResidue;
-                        brokerResidue = residue;
-                        if (residue.items && residue.items.length > 0) {
-                            const details = residue.items
-                                .map((item) => `[${item.kind}] ${item.name} (${item.path})：${item.reason}`)
-                                .join("；");
-                            checks.push({
-                                id: "host.dsm_residue",
-                                status: "warn",
-                                message: `發現 ${residue.items.length} 筆 DSM 殘留孤兒：${details}`,
-                                suggestion: "這會讓同 port／同名安裝失敗；需管理員以 root 清理，見 docs/impl/STATUS.md 教訓 17",
-                            });
-                        }
-                        else {
-                            checks.push({
-                                id: "host.dsm_residue",
-                                status: "pass",
-                                message: "無 DSM 殘留孤兒（.sc port profile 與 Container Manager 專案乾淨）",
-                            });
-                        }
-                    }
-                }
-                catch {
-                    // If query fails or Broker is old, omit / skip silently to be compatible
-                }
-            }
-            // Check 2.3c: administrator-only DSM PortInfo fallback / cross-check.
-            await appendDsmPortProfileCheck(checks, host, {
-                brokerInstalled,
-                brokerReady: isBrokerReady,
-                brokerResidue,
-            });
-            // 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") {
-                                    // Check the diagnosed route before treating a missing binding
-                                    // as a Broker-installer failure. Unknown is deliberately
-                                    // non-failing because the Broker may not be able to read the
-                                    // DSM package resource.
-                                    let packageRoute = "unknown";
-                                    if (host.getDsmDiagnostics) {
-                                        try {
-                                            const diag = await host.getDsmDiagnostics(targetPackageId);
-                                            packageRoute = packageRouteFromDiagnostics(diag);
-                                        }
-                                        catch {
-                                            // ignore
-                                        }
-                                    }
-                                    if (packageRoute === "package-only") {
-                                        checks.push({
-                                            id: "host.package_binding",
-                                            status: "skip",
-                                            message: "package-only 路線，無 Broker binding（略過）",
-                                        });
-                                    }
-                                    else if (packageRoute === "unknown") {
-                                        checks.push({
-                                            id: "host.package_binding",
-                                            status: "skip",
-                                            message: "Broker 無法判定套件路線，略過 Package Binding 檢查",
-                                        });
-                                    }
-                                    else {
-                                        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" ? "[✗]" : check.status === "warn" ? "[!]" : "[-]";
-        const codeTag = check.code ? ` [${check.code}]` : "";
-        lines.push(`${symbol} ${check.id}${codeTag}: ${check.message}`);
-        if ((check.status === "fail" || check.status === "warn") && check.suggestion) {
-            lines.push(`    建議：${check.suggestion}`);
-        }
-    }
-    lines.push("");
-    lines.push(report.ok ? "診斷全部通過。" : "診斷發現問題，請依照上述建議修正。");
-    return lines.join("\n");
-}