@synopackageland/cli 0.3.8 → 0.3.10

package/dist/cli.js

@@ -274,6 +274,9 @@ export async function runCli(argv) {
                 console.error(`[${result.code ?? "DEPLOY_FAILED"}] ${result.message ?? "部署失敗。"}`);
                 process.exit(1);
             }
+            for (const note of result.notes ?? []) {
+                console.warn(`[注意] ${note}`);
+            }
             console.log(`已部署 ${result.packageId}`);
             if (result.openUrl) {
                 console.log(`Open URL：${result.openUrl}`);

package/dist/deploy/deploy.d.ts

@@ -24,5 +24,7 @@ export interface DeployProjectResult {
     spkPath?: string;
     openUrl?: string;
     catalogVersion?: string;
+    /** Non-blocking pre-flight remarks, e.g. a read-only Shared Folder grant. */
+    notes?: string[];
 }
 export declare function deployProject(options: DeployProjectOptions): Promise<DeployProjectResult>;

package/dist/deploy/deploy.js

@@ -9,9 +9,12 @@ import { resolveDeployIdentity, PACKAGE_IDENTITY_MAX_LENGTH } from "./identity.j
 import { resolveDeploySpkVersion } from "./spk-version.js";
 import { resolveSharedFolderExtraValues, sharedFolderParameterNames } from "./share-values.js";
 import { resolveDsmUserExtraValues, dsmUserParameterNames } from "./run-as-values.js";
+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) {
@@ -124,6 +127,34 @@ export async function deployProject(options) {
     if (!runAsResolved.ok) {
         return { ok: false, code: runAsResolved.code, message: runAsResolved.message };
     }
+    // A42 pre-flight: preinst runs as the package user and can never read ACL, so
+    // the only place that can catch "selected user cannot reach selected Share" is
+    // here, where we still hold an administrator session. Refuses before install.
+    const sharePermission = await runSharePermissionPreflight({
+        shares: Object.fromEntries(sharedFolderParameterNames(contract)
+            .map((key) => [key, (options.shareValues ?? {})[key] ?? ""])
+            .filter(([, value]) => value.trim() !== "")),
+        runAsUsers: runAsResolved.extraValues,
+        listSharePermissions: options.host.listSharePermissions
+            ? (name) => options.host.listSharePermissions(name)
+            : undefined,
+        listUserGroups: options.host.listUserGroups
+            ? (name) => options.host.listUserGroups(name)
+            : undefined,
+    });
+    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,
@@ -273,5 +304,6 @@ export async function deployProject(options) {
         spkPath: build.outputPath,
         openUrl: info.openUrl ?? appOriginFromContract(options.host.dsmOrigin, contract),
         catalogVersion,
+        notes: sharePermission.notes.length > 0 ? sharePermission.notes : undefined,
     };
 }

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/deploy/share-permission-preflight.d.ts

@@ -0,0 +1,37 @@
+import { type SharePermissionRow } from "../host/share-permission.js";
+export declare const SHARE_RUN_AS_NO_ACCESS = "SHARE_RUN_AS_NO_ACCESS";
+export interface SharePermissionListing {
+    users: SharePermissionRow[];
+    groups: SharePermissionRow[];
+}
+export interface SharePermissionPreflightInput {
+    /** Logical Share names to check, keyed by the contract parameter name. */
+    shares: Record<string, string>;
+    /** Selected DSM user logical names, keyed by the contract parameter name. */
+    runAsUsers: Record<string, string>;
+    listSharePermissions?: (shareName: string) => Promise<SharePermissionListing | undefined>;
+    listUserGroups?: (userName: string) => Promise<string[] | undefined>;
+}
+export type SharePermissionPreflightResult = {
+    ok: true;
+    notes: string[];
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Ask the NAS, with the administrator session `deploy` already holds, whether
+ * every selected Run-as user can reach every selected Shared Folder.
+ *
+ * Deliberate boundaries:
+ * - This is a pre-flight, not enforcement. Package Center installs do not come
+ *   through here, and share permission can change after the install.
+ * - "Cannot tell" never becomes a refusal: a host without the capability, an
+ *   API that failed, an empty listing, or an advanced/Windows ACL (`is_custom`,
+ *   readable only by root-only synoacltool) all pass through.
+ * - `posix_all_shares` is out of scope on purpose. It means "mount every Share,
+ *   read-only" -- gating it on permission would refuse almost every install,
+ *   and the read-only bind already limits the damage.
+ */
+export declare function runSharePermissionPreflight(input: SharePermissionPreflightInput): Promise<SharePermissionPreflightResult>;

package/dist/deploy/share-permission-preflight.js

@@ -0,0 +1,81 @@
+import { evaluateShareAccess } from "../host/share-permission.js";
+export const SHARE_RUN_AS_NO_ACCESS = "SHARE_RUN_AS_NO_ACCESS";
+/**
+ * Ask the NAS, with the administrator session `deploy` already holds, whether
+ * every selected Run-as user can reach every selected Shared Folder.
+ *
+ * Deliberate boundaries:
+ * - This is a pre-flight, not enforcement. Package Center installs do not come
+ *   through here, and share permission can change after the install.
+ * - "Cannot tell" never becomes a refusal: a host without the capability, an
+ *   API that failed, an empty listing, or an advanced/Windows ACL (`is_custom`,
+ *   readable only by root-only synoacltool) all pass through.
+ * - `posix_all_shares` is out of scope on purpose. It means "mount every Share,
+ *   read-only" -- gating it on permission would refuse almost every install,
+ *   and the read-only bind already limits the damage.
+ */
+export async function runSharePermissionPreflight(input) {
+    const shareEntries = Object.entries(input.shares).filter(([, name]) => name.trim() !== "");
+    const userEntries = Object.entries(input.runAsUsers).filter(([, name]) => name.trim() !== "");
+    if (shareEntries.length === 0 || userEntries.length === 0) {
+        return { ok: true, notes: [] };
+    }
+    if (!input.listSharePermissions || !input.listUserGroups) {
+        return { ok: true, notes: [] };
+    }
+    const notes = [];
+    const groupCache = new Map();
+    const listingCache = new Map();
+    for (const [shareKey, shareName] of shareEntries) {
+        let listing = listingCache.get(shareName);
+        if (!listingCache.has(shareName)) {
+            try {
+                listing = await input.listSharePermissions(shareName);
+            }
+            catch {
+                listing = undefined;
+            }
+            listingCache.set(shareName, listing);
+        }
+        if (!listing) {
+            continue;
+        }
+        for (const [userKey, userName] of userEntries) {
+            let groups = groupCache.get(userName);
+            if (!groupCache.has(userName)) {
+                try {
+                    groups = await input.listUserGroups(userName);
+                }
+                catch {
+                    groups = undefined;
+                }
+                groupCache.set(userName, groups);
+            }
+            if (!groups) {
+                continue;
+            }
+            const verdict = evaluateShareAccess({
+                userName,
+                userGroups: groups,
+                userRows: listing.users,
+                groupRows: listing.groups,
+            });
+            if (verdict.access === "denied" || verdict.access === "none") {
+                const cause = verdict.access === "denied"
+                    ? `被「${verdict.deniedBy}」明確拒絕`
+                    : "在使用者本身與其所屬群組都沒有任何授權";
+                return {
+                    ok: false,
+                    code: SHARE_RUN_AS_NO_ACCESS,
+                    message: `Container Run-as「${userKey}=${userName}」對 Shared Folder「${shareKey}=${shareName}」${cause}。` +
+                        "容器會以該使用者的身分掛載這個 Share，安裝雖然會成功，但讀寫會在 runtime 拿到 Permission denied。" +
+                        `請先在 DSM 控制台把 ${shareName} 的權限給 ${userName}，或改選另一個使用者／Share。`,
+                };
+            }
+            if (verdict.access === "read") {
+                notes.push(`Run-as「${userName}」對 Shared Folder「${shareName}」只有唯讀權限（來源 ${verdict.grantedBy}）。若 App 需要寫入會在 runtime 失敗。`);
+            }
+        }
+    }
+    return { ok: true, notes };
+}

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

@@ -499,6 +499,16 @@ export const ERROR_REGISTRY = {
         description: "dsm_user 參數必須提供 DSM 使用者邏輯名稱，禁止使用數字 UID。",
         suggestion: "請在 --run-as 指定 DSM 使用者帳號名稱（例如 --run-as RUN_AS=alice）。",
     },
+    SHARE_RUN_AS_NO_ACCESS: {
+        code: "SHARE_RUN_AS_NO_ACCESS",
+        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

@@ -5,7 +5,10 @@ import { join } from "node:path";
 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";
@@ -234,6 +237,21 @@ function createDsmNasHost(credentials, profileName) {
         async listShareNames() {
             return listShareNamesWithSynoagentcli(profileName);
         },
+        async listSharePermissions(logicalName) {
+            return fetchSharePermissions(logicalName, createSynoagentcliApiCall(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);
@@ -352,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>;