@synopackageland/cli 0.3.8 → 0.3.10

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,4 +1,10 @@
+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">>;
 export interface FakeNasHostOptions {
     curated?: string[];
     dsmOrigin?: string;
@@ -6,6 +12,21 @@ export interface FakeNasHostOptions {
     installationId?: string;
     shareNames?: string[];
     shares?: Record<string, string>;
+    /**
+     * SYNO.Core.Share.Permission rows per Share, as partials -- every flag
+     * defaults to false, matching a row DSM grants nothing on. Omit the whole
+     * option to model a host that cannot answer the permission question.
+     */
+    sharePermissions?: Record<string, {
+        users: SharePermissionRowInput[];
+        groups: SharePermissionRowInput[];
+    }>;
+    /** 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;
@@ -13,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

@@ -1,4 +1,14 @@
 import { webStationAlias } from "../contract/web-launch.js";
+function sharePermissionRow(input) {
+    return {
+        is_admin: false,
+        is_writable: false,
+        is_readonly: false,
+        is_deny: false,
+        is_custom: false,
+        ...input,
+    };
+}
 export function createFakeNasHost(options = {}) {
     const dsmOrigin = options.dsmOrigin ?? "http://nas.example:5000";
     const installationId = options.installationId ?? "fake-installation";
@@ -32,6 +42,43 @@ export function createFakeNasHost(options = {}) {
         async listShareNames() {
             return [...shareNames];
         },
+        ...(options.sharePermissions
+            ? {
+                async listSharePermissions(logicalName) {
+                    const listing = options.sharePermissions?.[logicalName];
+                    if (!listing) {
+                        return undefined;
+                    }
+                    return {
+                        users: listing.users.map(sharePermissionRow),
+                        groups: listing.groups.map(sharePermissionRow),
+                    };
+                },
+            }
+            : {}),
+        ...(options.userGroups
+            ? {
+                async listUserGroups(userName) {
+                    return options.userGroups?.[userName];
+                },
+            }
+            : {}),
+        ...(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;
         },
@@ -123,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/share-permission-lookup.d.ts

@@ -0,0 +1,23 @@
+import type { SharePermissionListing } from "../deploy/share-permission-preflight.js";
+import type { SharePermissionRow } from "./share-permission.js";
+/**
+ * Reads DSM share permission with the administrator session `deploy` holds.
+ *
+ * Every parser returns `undefined` rather than an empty result when the answer
+ * is missing or malformed: downstream, `undefined` means "cannot tell" and lets
+ * the install proceed, while an empty list would read as a real denial and
+ * refuse the install on a transport error.
+ *
+ * The APIs used were confirmed present on DSM 7.4 (vt-nas):
+ * `SYNO.Core.Share.Permission`, `SYNO.Core.Group`, `SYNO.Core.Group.Member`.
+ * `SYNO.Core.User.Group` also exists on the NAS but has no generated
+ * synoagentcli operation, which is why membership is derived group-by-group.
+ */
+export type DsmApiCall = (operationId: string, params: Record<string, string>) => Promise<unknown>;
+export declare function parseSharePermissionRows(payload: unknown): SharePermissionRow[] | undefined;
+export declare function parseGroupNames(payload: unknown): string[] | undefined;
+export declare function parseGroupMemberNames(payload: unknown): string[] | undefined;
+export declare function fetchSharePermissions(shareName: string, call: DsmApiCall): Promise<SharePermissionListing | undefined>;
+export declare function fetchUserGroups(userName: string, call: DsmApiCall): Promise<string[] | undefined>;
+/** synoagentcli-backed `DsmApiCall`, matching how the rest of the host client talks to DSM. */
+export declare function createSynoagentcliApiCall(profileName?: string): DsmApiCall;

package/dist/host/share-permission-lookup.js

@@ -0,0 +1,149 @@
+import { spawnSync } from "node:child_process";
+const SHARE_PERMISSION_OPERATION = "SYNO_Core_Share_Permission_list_v1";
+const GROUP_LIST_OPERATION = "SYNO_Core_Group_list_v1";
+const GROUP_MEMBER_OPERATION = "SYNO_Core_Group_Member_list_v1";
+function asRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+/** Unwrap the synoagentcli envelope down to the DSM `data` object. */
+function dsmData(payload) {
+    const outer = asRecord(payload);
+    if (!outer || outer.success === false) {
+        return undefined;
+    }
+    const inner = asRecord(outer.data);
+    const response = asRecord(inner?.response);
+    return asRecord(response?.data) ?? asRecord(inner?.data);
+}
+function flag(record, key) {
+    return record[key] === true;
+}
+export function parseSharePermissionRows(payload) {
+    const data = dsmData(payload);
+    const items = data?.items;
+    if (!Array.isArray(items)) {
+        return undefined;
+    }
+    const rows = [];
+    for (const item of items) {
+        const record = asRecord(item);
+        const name = record?.name;
+        if (typeof name !== "string" || name === "") {
+            continue;
+        }
+        rows.push({
+            name,
+            is_admin: flag(record, "is_admin"),
+            is_writable: flag(record, "is_writable"),
+            is_readonly: flag(record, "is_readonly"),
+            is_deny: flag(record, "is_deny"),
+            is_custom: flag(record, "is_custom"),
+        });
+    }
+    return rows.length > 0 ? rows : undefined;
+}
+function parseNames(payload, key) {
+    const data = dsmData(payload);
+    const list = data?.[key];
+    if (!Array.isArray(list)) {
+        return undefined;
+    }
+    const names = [];
+    for (const item of list) {
+        const name = asRecord(item)?.name;
+        if (typeof name === "string" && name !== "") {
+            names.push(name);
+        }
+    }
+    return names;
+}
+export function parseGroupNames(payload) {
+    const names = parseNames(payload, "groups");
+    return names && names.length > 0 ? names : undefined;
+}
+export function parseGroupMemberNames(payload) {
+    return parseNames(payload, "users");
+}
+export async function fetchSharePermissions(shareName, call) {
+    const read = async (userGroupType) => {
+        try {
+            return parseSharePermissionRows(await call(SHARE_PERMISSION_OPERATION, {
+                name: shareName,
+                user_group_type: userGroupType,
+                offset: "0",
+                limit: "-1",
+            }));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const users = await read("local_user");
+    const groups = await read("local_group");
+    // A half-read listing could hide the very row that grants or denies access.
+    if (!users || !groups) {
+        return undefined;
+    }
+    return { users, groups };
+}
+export async function fetchUserGroups(userName, call) {
+    let groupNames;
+    try {
+        groupNames = parseGroupNames(await call(GROUP_LIST_OPERATION, { offset: "0", limit: "-1" }));
+    }
+    catch {
+        return undefined;
+    }
+    if (!groupNames) {
+        return undefined;
+    }
+    const memberships = [];
+    for (const groupName of groupNames) {
+        let members;
+        try {
+            members = parseGroupMemberNames(await call(GROUP_MEMBER_OPERATION, { group: groupName, offset: "0", limit: "-1" }));
+        }
+        catch {
+            return undefined;
+        }
+        // One unreadable group could be the one that grants access, so a partial
+        // membership set must never be used to refuse an install.
+        if (!members) {
+            return undefined;
+        }
+        if (members.includes(userName)) {
+            memberships.push(groupName);
+        }
+    }
+    return memberships;
+}
+/** synoagentcli-backed `DsmApiCall`, matching how the rest of the host client talks to DSM. */
+export function createSynoagentcliApiCall(profileName) {
+    return async (operationId, params) => {
+        const args = ["api", "call", "--operation-id", operationId];
+        for (const [key, value] of Object.entries(params)) {
+            args.push("--param", `${key}=${value}`);
+        }
+        if (profileName) {
+            args.push("--host", profileName);
+        }
+        const result = spawnSync("synoagentcli", args, { encoding: "utf8" });
+        if (result.status !== 0) {
+            return undefined;
+        }
+        // synoagentcli may prepend an update notice before the JSON body.
+        const match = /\{[\s\S]*\}/.exec(result.stdout ?? "");
+        if (!match) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(match[0]);
+        }
+        catch {
+            return undefined;
+        }
+    };
+}