@synopackageland/cli 0.3.9 → 0.3.10

package/dist/deploy/deploy.js

@@ -13,6 +13,8 @@ import { runSharePermissionPreflight } from "./share-permission-preflight.js";
 import { homesParameterNames, resolveHomesExtraValues } from "./homes-values.js";
 import { resolveInstallParameterExtraValues } from "./param-values.js";
 import { CURATED_BUILD_OFFSET } from "@synopackageland/package-source/index-manifest";
+import { loadCompose } from "../compose/analyze.js";
+import { runPortPreflight } from "./port-preflight.js";
 const CURATED_DEPLOY_REFUSED_MESSAGE = "此 NAS 已持有 Curated App Package Attestation。請改用 --dev，或使用 --replace-curated 明確降級。";
 const POSIX_ALL_SHARES_LOOKUP_FAILED = "DEPLOY_POSIX_ALL_SHARES_LOOKUP_FAILED";
 function brokerCapabilitiesFromContract(project) {
@@ -143,6 +145,16 @@ export async function deployProject(options) {
     if (!sharePermission.ok) {
         return { ok: false, code: sharePermission.code, message: sharePermission.message };
     }
+    const portPreflight = await runPortPreflight({
+        compose: loadCompose(options.project.composePath)?.compose,
+        packageIdentity: identity.packageId,
+        listPortInfo: options.host.listPortInfo
+            ? () => options.host.listPortInfo()
+            : undefined,
+    });
+    if (!portPreflight.ok) {
+        return { ok: false, code: portPreflight.code, message: portPreflight.message };
+    }
     const extraValues = {
         ...paramResolved.extraValues,
         ...homesResolved.extraValues,

package/dist/deploy/port-preflight.d.ts

@@ -0,0 +1,21 @@
+import type { ComposeDocument } from "../types.js";
+import { type PortInfoEntry } from "../host/port-info.js";
+export declare const PORT_ALREADY_IN_USE = "PORT_ALREADY_IN_USE";
+export interface PortPreflightInput {
+    compose?: ComposeDocument;
+    packageIdentity: string;
+    listPortInfo?: () => Promise<PortInfoEntry[] | undefined>;
+}
+export type PortPreflightResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: typeof PORT_ALREADY_IN_USE;
+    message: string;
+};
+/**
+ * Checks Compose's published TCP host ports against DSM's administrator-only
+ * PortInfo listing. Missing capability, transport failure, malformed data,
+ * and an empty listing all mean "cannot tell" and therefore pass through.
+ */
+export declare function runPortPreflight(input: PortPreflightInput): Promise<PortPreflightResult>;

package/dist/deploy/port-preflight.js

@@ -0,0 +1,42 @@
+import { collectPublishedTcpPorts } from "../compose/analyze.js";
+import { findPortConflicts, formatPortOccupant, } from "../host/port-info.js";
+export const PORT_ALREADY_IN_USE = "PORT_ALREADY_IN_USE";
+/**
+ * Checks Compose's published TCP host ports against DSM's administrator-only
+ * PortInfo listing. Missing capability, transport failure, malformed data,
+ * and an empty listing all mean "cannot tell" and therefore pass through.
+ */
+export async function runPortPreflight(input) {
+    const publishedPorts = input.compose
+        ? collectPublishedTcpPorts(input.compose)
+        : new Map();
+    if (publishedPorts.size === 0 || !input.listPortInfo) {
+        return { ok: true };
+    }
+    let portInfo;
+    try {
+        portInfo = await input.listPortInfo();
+    }
+    catch {
+        portInfo = undefined;
+    }
+    if (!portInfo || portInfo.length === 0) {
+        return { ok: true };
+    }
+    const conflicts = findPortConflicts({
+        publishedPorts,
+        packageIdentity: input.packageIdentity,
+        portInfo,
+    });
+    const conflict = conflicts[0];
+    if (!conflict) {
+        return { ok: true };
+    }
+    const occupants = conflict.occupants.map(formatPortOccupant).join("、");
+    return {
+        ok: false,
+        code: PORT_ALREADY_IN_USE,
+        message: `Published port ${conflict.port} 已被 ${occupants} 佔用（Compose service：${conflict.services.join("、")}）。` +
+            "請改用未被其他服務使用的 host port；同一 Package Identity 的既有容器會在升級／重裝時放行。",
+    };
+}

package/dist/doctor.js

@@ -6,6 +6,7 @@ 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":
@@ -67,6 +68,98 @@ function packageFailureSuggestion(state) {
         : "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) ---
@@ -450,11 +543,13 @@ export async function runDoctor(options) {
                 }
             }
             // 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}`)
@@ -479,6 +574,12 @@ export async function runDoctor(options) {
                     // 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) {

package/dist/error-registry.js

@@ -504,6 +504,11 @@ export const ERROR_REGISTRY = {
         description: "deploy 的安裝前檢查發現選定的 Container Run-as 使用者對選定的 Shared Folder 沒有權限（或被明確拒絕）。容器會以該使用者掛載該 Share，安裝會成功但 runtime 讀寫會拿到 Permission denied。",
         suggestion: "請在 DSM 控制台把該 Shared Folder 的權限授予該使用者（或其群組），或改選別的使用者／Share，再重新部署。此檢查只在 deploy 進行；Package Center 安裝精靈不經過這裡，ACL 仍是管理員的前提責任。",
     },
+    PORT_ALREADY_IN_USE: {
+        code: "PORT_ALREADY_IN_USE",
+        description: "deploy 的安裝前檢查發現 Compose published TCP port 已被其他服務或容器佔用。",
+        suggestion: "請更換 synology-app.yaml／compose.yaml 的 published host port；同一 Package Identity 的既有容器會在升級或重裝時放行。",
+    },
     CURATED_DEPLOY_REFUSED: {
         code: "CURATED_DEPLOY_REFUSED",
         description: "目標 NAS 已持有 Curated App Package Attestation，禁止隨意覆蓋部署。",

package/dist/host/dsm-client.js

@@ -6,7 +6,9 @@ import { IDENTITY_CGI_PATH } from "./broker-paths.js";
 import { packageSourceOrigin } from "../deploy/catalog-publish.js";
 import { listShareNamesWithSynoagentcli, lookupSharePathWithSynoagentcli } from "./share-lookup.js";
 import { createSynoagentcliApiCall, fetchSharePermissions, fetchUserGroups, } from "./share-permission-lookup.js";
+import { fetchPortInfo } from "./port-info-lookup.js";
 import { dsmFetch } from "./dsm-http.js";
+import { fetchDsmPortProfileInventory } from "./dsm-port-profile.js";
 import { installPackageFromCatalog, installPackageFromLocalSpk, uninstallPackageFromDsm, fetchInstalledPackageState, packageStateFromRecord, } from "./catalog-install.js";
 import { resolveHostCredentials } from "./credentials.js";
 const OIDC_COMPAT_PATH = "/api/v1/inner-loop/oidc-compat";
@@ -241,6 +243,15 @@ function createDsmNasHost(credentials, profileName) {
         async listUserGroups(userName) {
             return fetchUserGroups(userName, createSynoagentcliApiCall(profileName));
         },
+        async listPortInfo() {
+            try {
+                await ensureLogin();
+                return fetchPortInfo(dsmOrigin, cookieHeader ?? "");
+            }
+            catch {
+                return undefined;
+            }
+        },
         async resolveHomesPath() {
             try {
                 const result = synoagentcli(["dsm", "control-panel", "user-group", "advanced", "get", "--section", "home"], profileName);
@@ -359,6 +370,15 @@ function createDsmNasHost(credentials, profileName) {
                 return undefined;
             }
         },
+        async getDsmPortProfileInventory() {
+            try {
+                await ensureLogin();
+                return await fetchDsmPortProfileInventory(dsmOrigin, cookieHeader ?? "");
+            }
+            catch {
+                return undefined;
+            }
+        },
         async getOidcCompatSettings() {
             try {
                 await ensureLogin();

package/dist/host/dsm-port-profile.d.ts

@@ -0,0 +1,48 @@
+/** The precision caveat for the administrator-only fallback. */
+export declare const DSM_PORT_PROFILE_PRECISION_WARNING = "API \u7248\u672A\u8B80\u53D6 conf/resource\uFF1B\u82E5\u6709 App \u81EA\u8A02 Compose project \u540D\u53EF\u80FD\u8AA4\u5831";
+export interface DsmPortRange {
+    start: number;
+    end: number;
+}
+export interface DsmPortProfile {
+    portId: string;
+    containerName: string;
+    projectName: string;
+    /** Kept for diagnostics only; the API orphan test must use projectName. */
+    presumedPackageIdentity: string;
+    dstPorts: DsmPortRange[];
+}
+export interface DsmPortProfileInventory {
+    profiles: DsmPortProfile[];
+    orphaned: DsmPortProfile[];
+}
+/**
+ * Parses the Docker .sc filename using the same rules as the Broker's
+ * parsePortProfileFilename(). In particular, projectName is everything before
+ * the final two dash-separated container segments.
+ */
+export declare function parsePortProfileFilename(filename: string): {
+    containerName: string;
+    projectName: string;
+    presumedPackageIdentity: string;
+} | undefined;
+/** Parse one DSM dst_port value, including the documented range form. */
+export declare function parseDsmPortRange(value: string): DsmPortRange | undefined;
+/** Parse a successful SYNO.Core.Service.PortInfo/load response. */
+export declare function parseDsmPortInfoPayload(payload: unknown): DsmPortProfile[] | undefined;
+/** Parse the installed identity set from a successful DSM package list. */
+export declare function installedPackageIdentitiesFromPayload(payload: unknown): string[] | undefined;
+/**
+ * Build the API-only inventory from the two independent DSM responses.
+ *
+ * The package list is a forward mapping: package identity -> project name.
+ * Do not use presumedPackageIdentity here; replacing dashes with dots is
+ * lossy for identities such as com.example.hello-web.
+ */
+export declare function dsmPortProfileInventoryFromPayloads(portInfoPayload: unknown, packageListPayload: unknown): DsmPortProfileInventory | undefined;
+/**
+ * Read PortInfo.load and the administrator-visible installed package list.
+ * Any transport, HTTP, JSON, or DSM API failure becomes undefined so callers
+ * can skip without inventing residue.
+ */
+export declare function fetchDsmPortProfileInventory(dsmOrigin: string, cookieHeader: string): Promise<DsmPortProfileInventory | undefined>;

package/dist/host/dsm-port-profile.js

@@ -0,0 +1,208 @@
+import { basename } from "node:path";
+import { composeProjectName } from "../build-spk/resource-worker.js";
+import { dsmFetch } from "./dsm-http.js";
+/** The precision caveat for the administrator-only fallback. */
+export const DSM_PORT_PROFILE_PRECISION_WARNING = "API 版未讀取 conf/resource；若有 App 自訂 Compose project 名可能誤報";
+/**
+ * Parses the Docker .sc filename using the same rules as the Broker's
+ * parsePortProfileFilename(). In particular, projectName is everything before
+ * the final two dash-separated container segments.
+ */
+export function parsePortProfileFilename(filename) {
+    const base = basename(filename);
+    if (!base.startsWith("docker_") || !base.endsWith(".sc")) {
+        return undefined;
+    }
+    const containerName = base.slice("docker_".length, base.length - ".sc".length);
+    if (!containerName) {
+        return undefined;
+    }
+    // Keep this split aligned with packages/broker/src/diagnostics/dsm-residue.ts:
+    // remove the final -<service>-<replica> pair, not an identity-specific guess.
+    const lastDash = containerName.lastIndexOf("-");
+    if (lastDash <= 0) {
+        return undefined;
+    }
+    const secondLastDash = containerName.lastIndexOf("-", lastDash - 1);
+    if (secondLastDash <= 0) {
+        return undefined;
+    }
+    const projectName = containerName.slice(0, secondLastDash);
+    const presumedPackageIdentity = projectName.replace(/-/g, ".");
+    return {
+        containerName,
+        projectName,
+        presumedPackageIdentity,
+    };
+}
+/** Parse one DSM dst_port value, including the documented range form. */
+export function parseDsmPortRange(value) {
+    const match = /^([0-9]{1,5})(?:-([0-9]{1,5}))?$/.exec(value.trim());
+    if (!match) {
+        return undefined;
+    }
+    const start = Number(match[1]);
+    const end = Number(match[2] ?? match[1]);
+    if (!Number.isInteger(start) ||
+        !Number.isInteger(end) ||
+        start < 1 ||
+        end > 65535 ||
+        start > end) {
+        return undefined;
+    }
+    return { start, end };
+}
+function parseDsmPortRanges(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return undefined;
+    }
+    const ranges = [];
+    for (const entry of value) {
+        if (typeof entry !== "string") {
+            return undefined;
+        }
+        const range = parseDsmPortRange(entry);
+        if (!range) {
+            return undefined;
+        }
+        ranges.push(range);
+    }
+    return ranges;
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function parseDockerPortInfo(value) {
+    const entry = record(value);
+    if (!entry) {
+        return undefined;
+    }
+    // PortInfo also contains ordinary DSM service rows. Only the documented
+    // Docker(TCP) rows correspond to docker_<container>.sc profiles.
+    if (entry.protocol !== "tcp" || entry.name !== "Docker(TCP)") {
+        return undefined;
+    }
+    const portId = nonEmptyString(entry.port_id);
+    if (!portId?.endsWith("_tcp")) {
+        return undefined;
+    }
+    const containerName = portId.slice(0, -"_tcp".length);
+    if (!containerName || entry.desc !== `Docker ${containerName}`) {
+        return undefined;
+    }
+    const parsed = parsePortProfileFilename(`docker_${containerName}.sc`);
+    const dstPorts = parseDsmPortRanges(entry.dst_port);
+    if (!parsed || !dstPorts) {
+        return undefined;
+    }
+    return {
+        portId,
+        containerName: parsed.containerName,
+        projectName: parsed.projectName,
+        presumedPackageIdentity: parsed.presumedPackageIdentity,
+        dstPorts,
+    };
+}
+/** Parse a successful SYNO.Core.Service.PortInfo/load response. */
+export function parseDsmPortInfoPayload(payload) {
+    const root = record(payload);
+    const data = record(root?.data);
+    if (root?.success !== true || !data || !Array.isArray(data.port_info)) {
+        return undefined;
+    }
+    return data.port_info.flatMap((entry) => {
+        const profile = parseDockerPortInfo(entry);
+        return profile ? [profile] : [];
+    });
+}
+/** Parse the installed identity set from a successful DSM package list. */
+export function installedPackageIdentitiesFromPayload(payload) {
+    const root = record(payload);
+    const data = record(root?.data);
+    if (root?.success !== true || !data || !Array.isArray(data.packages)) {
+        return undefined;
+    }
+    return [
+        ...new Set(data.packages
+            .map((entry) => record(entry)?.id)
+            .filter((id) => typeof id === "string" && id.length > 0)),
+    ];
+}
+/**
+ * Build the API-only inventory from the two independent DSM responses.
+ *
+ * The package list is a forward mapping: package identity -> project name.
+ * Do not use presumedPackageIdentity here; replacing dashes with dots is
+ * lossy for identities such as com.example.hello-web.
+ */
+export function dsmPortProfileInventoryFromPayloads(portInfoPayload, packageListPayload) {
+    const profiles = parseDsmPortInfoPayload(portInfoPayload);
+    if (!profiles) {
+        return undefined;
+    }
+    // An empty PortInfo list is a safe, successful "nothing to report" result;
+    // there is no reason to turn an unavailable package list into an orphan.
+    if (profiles.length === 0) {
+        return { profiles, orphaned: [] };
+    }
+    const installedPackages = installedPackageIdentitiesFromPayload(packageListPayload);
+    // An empty or unavailable package list cannot prove that any profile is an
+    // orphan. Fail closed instead of classifying every visible Docker row.
+    if (!installedPackages || installedPackages.length === 0) {
+        return undefined;
+    }
+    const declaredProjectNames = new Set(installedPackages.map(composeProjectName));
+    const orphaned = profiles.filter((profile) => !declaredProjectNames.has(profile.projectName));
+    return { profiles, orphaned };
+}
+async function fetchJson(dsmOrigin, cookieHeader, params) {
+    const query = new URLSearchParams(params);
+    const response = await dsmFetch(`${dsmOrigin}/webapi/entry.cgi?${query.toString()}`, {
+        headers: { cookie: cookieHeader },
+    });
+    if (!response.ok) {
+        return undefined;
+    }
+    try {
+        return await response.json();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read PortInfo.load and the administrator-visible installed package list.
+ * Any transport, HTTP, JSON, or DSM API failure becomes undefined so callers
+ * can skip without inventing residue.
+ */
+export async function fetchDsmPortProfileInventory(dsmOrigin, cookieHeader) {
+    try {
+        const portInfoPayload = await fetchJson(dsmOrigin, cookieHeader, {
+            api: "SYNO.Core.Service.PortInfo",
+            version: "1",
+            method: "load",
+        });
+        const profiles = parseDsmPortInfoPayload(portInfoPayload);
+        if (!profiles) {
+            return undefined;
+        }
+        if (profiles.length === 0) {
+            return { profiles, orphaned: [] };
+        }
+        const packageListPayload = await fetchJson(dsmOrigin, cookieHeader, {
+            api: "SYNO.Core.Package",
+            version: "2",
+            method: "list",
+            additional: JSON.stringify(["status"]),
+        });
+        return dsmPortProfileInventoryFromPayloads(portInfoPayload, packageListPayload);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/host/fake-nas.d.ts

@@ -1,5 +1,7 @@
 import type { SharePermissionRow } from "./share-permission.js";
+import type { PortInfoEntry } from "./port-info.js";
 import type { AttestationKind, HostInstallRecord, HostOidcCompatSettings, NasHost, PackageRoute } from "./types.js";
+import type { DsmPortProfileInventory } from "./dsm-port-profile.js";
 export type SharePermissionRowInput = {
     name: string;
 } & Partial<Omit<SharePermissionRow, "name">>;
@@ -21,6 +23,10 @@ export interface FakeNasHostOptions {
     }>;
     /** Group membership per DSM user, for share-permission resolution. */
     userGroups?: Record<string, string[]>;
+    /** SYNO.Core.Service.PortInfo rows; omit to model a host without the capability. */
+    portInfo?: PortInfoEntry[];
+    /** Model a host whose PortInfo capability is present but the API failed. */
+    portInfoFailure?: boolean;
     installedEnv?: Record<string, Record<string, string>>;
     diagnostics?: {
         dsmResidue?: import("./types.js").DsmResidueInventory;
@@ -28,6 +34,8 @@ export interface FakeNasHostOptions {
         isPackageOnly?: boolean;
         [key: string]: unknown;
     };
+    /** Administrator-only DSM PortInfo inventory, when the fake should expose it. */
+    portProfileInventory?: DsmPortProfileInventory;
     /** Omit to model an older Broker without the OIDC settings endpoint. */
     oidcCompat?: HostOidcCompatSettings;
 }

package/dist/host/fake-nas.js

@@ -63,6 +63,22 @@ export function createFakeNasHost(options = {}) {
                 },
             }
             : {}),
+        ...(options.portInfo !== undefined || options.portInfoFailure
+            ? {
+                async listPortInfo() {
+                    if (options.portInfoFailure) {
+                        return undefined;
+                    }
+                    return options.portInfo?.map((entry) => ({
+                        ...entry,
+                        dst_port: [...entry.dst_port],
+                        ...(entry.src_port === undefined
+                            ? {}
+                            : { src_port: entry.src_port === null ? null : [...entry.src_port] }),
+                    }));
+                },
+            }
+            : {}),
         async resolveHomesPath() {
             return options.homesPath;
         },
@@ -154,6 +170,9 @@ export function createFakeNasHost(options = {}) {
         async getDsmDiagnostics() {
             return options.diagnostics;
         },
+        async getDsmPortProfileInventory() {
+            return options.portProfileInventory;
+        },
         async getOidcCompatSettings() {
             if (!options.oidcCompat) {
                 return undefined;

package/dist/host/port-info-lookup.d.ts

@@ -0,0 +1,9 @@
+import type { PortInfoEntry } from "./port-info.js";
+export type PortInfoHttpRequest = (url: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Parses the native DSM response, not a synoagentcli operation envelope.
+ * `undefined` means "cannot tell" and deliberately allows deployment to
+ * continue. An empty `port_info` list has the same fail-open meaning.
+ */
+export declare function parsePortInfo(payload: unknown): PortInfoEntry[] | undefined;
+export declare function fetchPortInfo(dsmOrigin: string, cookieHeader: string, request?: PortInfoHttpRequest): Promise<PortInfoEntry[] | undefined>;

package/dist/host/port-info-lookup.js

@@ -0,0 +1,87 @@
+import { dsmFetch } from "./dsm-http.js";
+const PORT_INFO_API = "SYNO.Core.Service.PortInfo";
+function asRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+function validPortRange(value) {
+    const match = /^(\d+)(?:\s*-\s*(\d+))?$/.exec(value.trim());
+    if (!match) {
+        return false;
+    }
+    const start = Number(match[1]);
+    const end = Number(match[2] ?? match[1]);
+    return (Number.isSafeInteger(start) &&
+        Number.isSafeInteger(end) &&
+        start >= 1 &&
+        start <= end &&
+        end <= 65535);
+}
+/**
+ * Parses the native DSM response, not a synoagentcli operation envelope.
+ * `undefined` means "cannot tell" and deliberately allows deployment to
+ * continue. An empty `port_info` list has the same fail-open meaning.
+ */
+export function parsePortInfo(payload) {
+    const outer = asRecord(payload);
+    const data = asRecord(outer?.data);
+    const items = data?.port_info;
+    if (outer?.success !== true || !Array.isArray(items) || items.length === 0) {
+        return undefined;
+    }
+    const entries = [];
+    for (const item of items) {
+        const record = asRecord(item);
+        if (!record) {
+            return undefined;
+        }
+        const desc = record?.desc;
+        const dstPort = record?.dst_port;
+        const name = record?.name;
+        const portId = record?.port_id;
+        const protocol = record?.protocol;
+        if (typeof desc !== "string" ||
+            typeof name !== "string" ||
+            typeof portId !== "string" ||
+            typeof protocol !== "string" ||
+            !Array.isArray(dstPort) ||
+            dstPort.length === 0 ||
+            !dstPort.every((value) => typeof value === "string" && validPortRange(value))) {
+            return undefined;
+        }
+        const srcPort = record.src_port;
+        if (srcPort !== undefined &&
+            srcPort !== null &&
+            (!Array.isArray(srcPort) || !srcPort.every((value) => typeof value === "string"))) {
+            return undefined;
+        }
+        entries.push({
+            desc,
+            dst_port: [...dstPort],
+            name,
+            port_id: portId,
+            protocol,
+            ...(srcPort === undefined ? {} : { src_port: srcPort === null ? null : [...srcPort] }),
+        });
+    }
+    return entries;
+}
+export async function fetchPortInfo(dsmOrigin, cookieHeader, request = dsmFetch) {
+    try {
+        const query = new URLSearchParams({
+            api: PORT_INFO_API,
+            version: "1",
+            method: "load",
+        });
+        const response = await request(`${dsmOrigin.replace(/\/$/, "")}/webapi/entry.cgi?${query.toString()}`, { headers: { cookie: cookieHeader } });
+        if (!response.ok) {
+            return undefined;
+        }
+        return parsePortInfo(await response.json());
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/host/port-info.d.ts

@@ -0,0 +1,33 @@
+/** One row returned by SYNO.Core.Service.PortInfo/load. */
+export interface PortInfoEntry {
+    desc: string;
+    dst_port: readonly string[];
+    name: string;
+    port_id: string;
+    protocol: string;
+    src_port?: readonly string[] | null;
+}
+export type DsmPortInfoEntry = PortInfoEntry;
+export type PortInfoRow = PortInfoEntry;
+export interface PortConflict {
+    port: number;
+    services: readonly string[];
+    occupants: readonly PortInfoEntry[];
+}
+/**
+ * Returns the Docker container name represented by a DSM port row, when the
+ * row has Docker's known `port_id` or `desc` shape. Other DSM services are
+ * intentionally returned as undefined so they remain conflicts.
+ */
+export declare function dockerContainerName(entry: PortInfoEntry): string | undefined;
+export declare function formatPortOccupant(entry: PortInfoEntry): string;
+/**
+ * Finds occupied published ports, ignoring only containers that are one of
+ * the Compose containers for this exact package identity. A same-identity
+ * occupant is the existing install being upgraded or reinstalled.
+ */
+export declare function findPortConflicts(input: {
+    publishedPorts: ReadonlyMap<number, readonly string[]>;
+    packageIdentity: string;
+    portInfo: readonly PortInfoEntry[];
+}): PortConflict[];

package/dist/host/port-info.js

@@ -0,0 +1,66 @@
+import { composeProjectName } from "../build-spk/resource-worker.js";
+function parsePortRange(value) {
+    const match = /^(\d+)(?:\s*-\s*(\d+))?$/.exec(value.trim());
+    if (!match) {
+        return undefined;
+    }
+    const start = Number(match[1]);
+    const end = Number(match[2] ?? match[1]);
+    if (!Number.isSafeInteger(start) ||
+        !Number.isSafeInteger(end) ||
+        start < 1 ||
+        end > 65535 ||
+        start > end) {
+        return undefined;
+    }
+    return { start, end };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function entryCoversPort(entry, port) {
+    return entry.dst_port.some((value) => {
+        const range = parsePortRange(value);
+        return range !== undefined && range.start <= port && port <= range.end;
+    });
+}
+/**
+ * Returns the Docker container name represented by a DSM port row, when the
+ * row has Docker's known `port_id` or `desc` shape. Other DSM services are
+ * intentionally returned as undefined so they remain conflicts.
+ */
+export function dockerContainerName(entry) {
+    const portIdMatch = /^(.*)_tcp$/i.exec(entry.port_id.trim());
+    if (portIdMatch?.[1]) {
+        return portIdMatch[1];
+    }
+    const descMatch = /^Docker\s+(.+)$/i.exec(entry.desc.trim());
+    return descMatch?.[1]?.trim() || undefined;
+}
+export function formatPortOccupant(entry) {
+    return dockerContainerName(entry) ?? (entry.desc.trim() || entry.port_id.trim() || entry.name.trim());
+}
+/**
+ * Finds occupied published ports, ignoring only containers that are one of
+ * the Compose containers for this exact package identity. A same-identity
+ * occupant is the existing install being upgraded or reinstalled.
+ */
+export function findPortConflicts(input) {
+    const conflicts = [];
+    const projectName = composeProjectName(input.packageIdentity);
+    for (const [port, services] of input.publishedPorts) {
+        // Compose names a container <project>-<service>-<replica>. Match the
+        // replica as a number rather than assuming -1: a scaled service would
+        // otherwise look like a foreign occupant and refuse this package's own
+        // redeploy. The service name is still matched exactly, so a different
+        // package whose project name merely shares a prefix stays a conflict.
+        const ownContainer = (containerName) => services.some((service) => new RegExp(`^${escapeRegExp(`${projectName}-${service}-`)}\\d+$`).test(containerName));
+        const occupants = input.portInfo.filter((entry) => entry.protocol.trim().toLowerCase() === "tcp" &&
+            entryCoversPort(entry, port) &&
+            !ownContainer(dockerContainerName(entry) ?? ""));
+        if (occupants.length > 0) {
+            conflicts.push({ port, services, occupants });
+        }
+    }
+    return conflicts;
+}

package/dist/host/types.d.ts

@@ -1,5 +1,7 @@
 import type { SharePermissionListing } from "../deploy/share-permission-preflight.js";
 import type { InstalledPackageState } from "./catalog-install.js";
+import type { PortInfoEntry } from "./port-info.js";
+import type { DsmPortProfileInventory } from "./dsm-port-profile.js";
 export type AttestationKind = "local" | "app-package" | "none";
 export type PackageRoute = "package-only" | "broker-installer" | "unknown";
 export type OidcOriginKind = "public-ca" | "quickconnect" | "lan-ip" | "self-signed" | "private-ca" | "http";
@@ -88,6 +90,8 @@ export interface NasHost {
     listSharePermissions?(logicalName: string): Promise<SharePermissionListing | undefined>;
     /** Group names a DSM user belongs to, for resolving share permission. */
     listUserGroups?(userName: string): Promise<string[] | undefined>;
+    /** Read SYNO.Core.Service.PortInfo/load using an administrator session. */
+    listPortInfo?(): Promise<PortInfoEntry[] | undefined>;
     /** Resolve the NAS-specific user-home root when DSM User Home is enabled. */
     resolveHomesPath?(): Promise<string | undefined>;
     getInstalledProjectEnv?(packageIdentity: string): Promise<Record<string, string> | undefined>;
@@ -103,6 +107,12 @@ export interface NasHost {
         isPackageOnly?: boolean;
         [key: string]: unknown;
     } | undefined>;
+    /**
+     * Read DSM PortInfo plus the administrator-visible installed package list.
+     * This path does not require SynoPkgLandService; undefined means the host
+     * could not answer and must be treated as unknown by diagnostics.
+     */
+    getDsmPortProfileInventory?(): Promise<DsmPortProfileInventory | undefined>;
     /** Read the optional administrator OIDC compatibility settings endpoint. */
     getOidcCompatSettings?(): Promise<HostOidcCompatSettings | undefined>;
     smokeRequireLogin(input: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {