@synopackageland/cli 0.3.7 → 0.3.9

package/dist/build-spk/generator.js

@@ -185,6 +185,7 @@ export async function buildSpk(options) {
             const resourceProjectDir = join(staging, "package", "compose");
             mkdirSync(resourceProjectDir, { recursive: true });
             const dsmUserParam = collectInstallParameters(contract).find((p) => p.param.type === "dsm_user");
+            let composeContent;
             if (dsmUserParam || rwEligibility?.headless === true || hasOidcCompat(contract)) {
                 const rawYaml = readFileSync(options.project.composePath, "utf8");
                 const doc = parseDocument(rawYaml);
@@ -222,16 +223,17 @@ export async function buildSpk(options) {
                 if (rwEligibility?.headless === true) {
                     injectHeadlessProbeVolume(doc);
                 }
-                let composeContent = doc.toString();
+                composeContent = doc.toString();
                 if (dsmUserParam) {
                     const escaped = `\\$\\{${dsmUserParam.name}_UID\\}:\\$\\{${dsmUserParam.name}_GID\\}`;
                     composeContent = composeContent.replace(new RegExp(`^([ \\t]*)user:\\s*"${escaped}"`, "gm"), `$1user: "\${${dsmUserParam.name}_UID}:\${${dsmUserParam.name}_GID}"\n$1# synopkgland:group_add ${dsmUserParam.name}`);
                 }
-                writeFileSync(join(resourceProjectDir, "docker-compose.yml"), composeContent, "utf8");
             }
             else {
-                copyFileSync(options.project.composePath, join(resourceProjectDir, "docker-compose.yml"));
+                composeContent = readFileSync(options.project.composePath, "utf8");
             }
+            composeContent = injectPosixAllSharesMarkers(composeContent, contract);
+            writeFileSync(join(resourceProjectDir, "docker-compose.yml"), composeContent, "utf8");
             chmodSync(join(resourceProjectDir, "docker-compose.yml"), FILE_MODE);
             if (rwEligibility?.headless === true) {
                 const probePayloadDir = join(resourceProjectDir, ".synopkgland");
@@ -354,6 +356,7 @@ function renderPrivilege() {
 }
 const SHARED_FOLDER_MOUNT_CONSENT = "此 App 會用你在這台 NAS 選的資料夾；整顆應用都看得到。Shared Folder Mount 是整個 App Instance 的 container access：能打開這個 App 的使用者，容器裡的程式都看得到該 Share，即使該使用者在 File Station 看不到。這不是逐使用者 DSM ACL。要依登入者權限讀寫 NAS 檔案，必須另外核准廣域 files.* 並走 File Gateway。";
 const HOMES_MOUNT_CONSENT = "此 App 會使用這台 NAS 已啟用的 User Home；整顆應用的容器都看得到，容器路徑由 Compose 決定。這不是逐使用者 DSM ACL；要依登入者權限讀寫 NAS 檔案，必須另外核准廣域 files.* 並走 File Gateway。";
+const POSIX_ALL_SHARES_MAX_WARNING = "掛載這台 NAS 目前列出的每一個共用資料夾。容器內可讀（或讀寫，依 Compose 模式）所有這些資料夾的檔案。安裝後新建的共用資料夾不會自動加入。由管理員決定是否安裝。";
 const DSM_USER_RUN_AS_CONSENT = "寫進 Share 的新檔在 File Station 顯示為你選的那位 DSM 使用者。點開此 App 的人共用這個磁碟身分，不是逐登入 ACL。";
 const DSM_USER_UPGRADE_CONSENT = "升級時更換 Container Run-as 不會 chown Share 上的舊檔；只有升級後寫入的新檔才會使用新的磁碟身分。";
 const SHARED_FOLDER_RW_UPGRADE_CONSENT = "此版本把 Share 掛載改為讀寫；容器可讀取並寫入你選的 Share，不再是唯讀。";
@@ -451,6 +454,29 @@ function injectHeadlessProbeVolume(doc) {
     }
     doc.setIn(["services", serviceName, "volumes"], volumes);
 }
+function injectPosixAllSharesMarkers(composeContent, contract) {
+    const names = collectInstallParameters(contract)
+        .filter(({ param }) => param.type === "posix_all_shares")
+        .map(({ name }) => name);
+    if (names.length === 0) {
+        return composeContent;
+    }
+    const declared = new Set(names);
+    const lines = composeContent.split("\n");
+    const output = [];
+    for (const line of lines) {
+        const match = line.match(/^(\s*)-\s*["']?\$\{([A-Za-z_][A-Za-z0-9_]*)\}:/);
+        const name = match?.[2];
+        if (match && name && declared.has(name)) {
+            const marker = `# synopkgland:posix_all_shares ${name}`;
+            if (output.at(-1)?.trim() !== marker) {
+                output.push(`${match[1]}${marker}`);
+            }
+        }
+        output.push(line);
+    }
+    return output.join("\n");
+}
 const PRIVILEGE_MAX_WARNING = "此 App 的容器有高權限，接近這台 NAS 的 root、幾乎整台機器。是否安裝由你這位管理員決定。";
 function renderInstallWizard(contract, compose) {
     const items = [];
@@ -557,6 +583,39 @@ function renderInstallWizard(contract, compose) {
             });
             continue;
         }
+        if (param.type === "posix_all_shares") {
+            items.push({
+                type: "textblock",
+                desc: POSIX_ALL_SHARES_MAX_WARNING,
+            });
+            items.push({
+                type: "combobox",
+                multiSelect: true,
+                desc: `POSIX all shares: ${name}`,
+                subitems: [{
+                        key: name,
+                        desc: name,
+                        displayField: "name",
+                        valueField: "name",
+                        multiSelect: true,
+                        editable: false,
+                        forceSelection: true,
+                        autoSelect: false,
+                        mode: "remote",
+                        api_store: {
+                            api: "SYNO.Core.Share",
+                            method: "list",
+                            version: 1,
+                            baseParams: { limit: -1, offset: 0 },
+                            root: "shares",
+                            idProperty: "name",
+                            fields: ["name"],
+                        },
+                        validator: { allowBlank: false },
+                    }],
+            });
+            continue;
+        }
         if (param.type === "dsm_user") {
             items.push({
                 type: "combobox",
@@ -654,6 +713,7 @@ function renderDynamicPreinstMaterializer(contract) {
     const allParams = collectInstallParameters(contract);
     const scalarParams = allParams.filter(({ param }) => param.type === "string" || param.type === "boolean");
     const sharedFolderParams = allParams.filter(({ param }) => param.type === "shared_folder");
+    const posixAllSharesParams = allParams.filter(({ param }) => param.type === "posix_all_shares");
     const dsmUserParam = allParams.find(({ param }) => param.type === "dsm_user");
     const lines = [
         "#!/bin/sh",
@@ -716,9 +776,12 @@ function renderDynamicPreinstMaterializer(contract) {
         "  esac",
         "}",
     ];
-    if (sharedFolderParams.length > 0) {
+    if (sharedFolderParams.length > 0 || posixAllSharesParams.length > 0) {
         lines.push("resolve_shared_folder() {", "  share_name=\"$1\"", "  case \"$share_name\" in", "    */*|*..*) die \"invalid share name $share_name\" ;;", "    '') die \"share name is empty\" ;;", "  esac", "  mounts_file=\"${D54_MOUNTS_FILE:-/proc/mounts}\"", "  if [ ! -r \"$mounts_file\" ] && [ -r \"/etc/mtab\" ]; then", "    mounts_file=\"/etc/mtab\"", "  fi", "  if [ ! -r \"$mounts_file\" ]; then", "    die \"cannot read mount points from $mounts_file\"", "  fi", "  vols=\"$(awk '$2 ~ /^\\/volume[0-9]+$/ {print $2}' \"$mounts_file\" | sort -u)\"", '  if [ -z "$vols" ]; then', "    vols=\"$(awk '{print $2}' \"$mounts_file\" | sort -u)\"", "  fi", "  matched=\"\"", "  count=0", "  for v in $vols; do", "    if [ -d \"$v/$share_name\" ]; then", "      matched=\"$v/$share_name\"", "      count=$((count + 1))", "    fi", "  done", "  if [ \"$count\" -eq 0 ]; then", "    die \"share $share_name not found on any volume\"", "  elif [ \"$count\" -gt 1 ]; then", "    die \"share $share_name matched multiple volumes\"", "  fi", "  printf '%s' \"$matched\"", "}");
     }
+    if (posixAllSharesParams.length > 0) {
+        lines.push("normalize_posix_all_shares() {", "  value=\"$1\"", "  case \"$value\" in", "    \\[*\\]) value=\"$(printf '%s' \"$value\" | sed 's/^[[:space:]]*\\[//; s/\\][[:space:]]*$//; s/\"//g')\" ;;", "  esac", "  printf '%s' \"$value\" | awk -F, '{ for (i = 1; i <= NF; i++) { gsub(/^[ \\t]+|[ \\t]+$/, \"\", $i); if ($i != \"\") print $i } }'", "}", "resolve_posix_all_shares() {", "  raw_list=\"$1\"", "  normalized=\"$(normalize_posix_all_shares \"$raw_list\")\"", "  [ -n \"$normalized\" ] || die \"POSIX_ALL_SHARES_EMPTY\"", "  names=\"\"", "  paths=\"\"", "  count=0", "  while IFS= read -r share_name; do", "    case \"$share_name\" in", "      */*|*..*|@*|'') die \"invalid Share name $share_name\" ;;", "      *[[:cntrl:]]*) die \"invalid Share name $share_name\" ;;", "    esac", "    share_path=\"$(resolve_shared_folder \"$share_name\")\"", "    names=\"${names}${names:+,}${share_name}\"", "    paths=\"${paths}${paths:+,}${share_path}\"", "    count=$((count + 1))", "  done <<EOF", "$normalized", "EOF", "  [ \"$count\" -gt 0 ] || die \"POSIX_ALL_SHARES_EMPTY\"", "  printf '%s\\n%s\\n%s' \"$names\" \"$paths\" \"$count\"", "}", "rewrite_posix_all_shares() {", "  p_name=\"$1\"", "  share_names=\"$2\"", "  share_paths=\"$3\"", "  compose_file=\"$4\"", "  [ -f \"$compose_file\" ] || die \"compose file missing at $compose_file\"", "  [ ! -L \"$compose_file\" ] || die \"compose file is a symlink\"", "  tmp_compose=\"$(mktemp \"${compose_file}.tmp.XXXXXX\")\"", "  awk -v param=\"$p_name\" -v share_names=\"$share_names\" -v share_paths=\"$share_paths\" '", "    BEGIN {", "      name_count = split(share_names, names, \",\")", "      path_count = split(share_paths, paths, \",\")", "      marker = \"# synopkgland:posix_all_shares \" param", "      pending = 0", "      single_quote = sprintf(\"%c\", 39)", "    }", "    {", "      if (index($0, marker) > 0 && $0 ~ /^[ \\t]*# synopkgland:posix_all_shares /) {", "        print $0", "        pending = 1", "        next", "      }", "      if (!pending) { print $0; next }", "      pending = 0", "      line = $0", "      indent = line", "      sub(/[^ \\t].*$/, \"\", indent)", "      entry = line", "      sub(/^[ \\t]*-[ \\t]*/, \"\", entry)", "      if (entry ~ /^\".*\"$/) entry = substr(entry, 2, length(entry) - 2)", "      if (length(entry) >= 2 && substr(entry, 1, 1) == single_quote && substr(entry, length(entry), 1) == single_quote) entry = substr(entry, 2, length(entry) - 2)", "      split(entry, fields, \":\")", "      if (fields[1] != \"${\" param \"}\" || fields[2] == \"\") { print $0; next }", "      mode = \"\"", "      if (length(fields) >= 3) mode = \":\" fields[3]", "      for (i = 1; i <= name_count && i <= path_count; i++) {", "        print indent \"- \" paths[i] \":\" fields[2] \"/\" names[i] mode", "      }", "    }", "  ' \"$compose_file\" > \"$tmp_compose\" || die \"failed to expand POSIX all-shares in $compose_file\"", "  mv \"$tmp_compose\" \"$compose_file\" || die \"failed to replace $compose_file\"", "}");
+    }
     if (dsmUserParam) {
         lines.push("resolve_dsm_user() {", "  user_name=\"$1\"", "  case \"$user_name\" in", "    */*|*..*|*[[:cntrl:]]*) die \"invalid user name $user_name\" ;;", "    '') die \"user name is empty\" ;;", "  esac", "  u_uid=\"$(id -u -- \"$user_name\" 2>/dev/null || true)\"", "  case \"$u_uid\" in", "    ''|*[!0-9]*) die \"resolved uid for $user_name is not a valid integer\" ;;", "    0) die \"resolved uid for $user_name cannot be 0 (root)\" ;;", "  esac", "  u_gid=\"$(id -g -- \"$user_name\" 2>/dev/null || true)\"", "  case \"$u_gid\" in", "    ''|*[!0-9]*) die \"resolved gid for $user_name is not a valid integer\" ;;", "  esac", "  # id -G returns all group ids including primary", "  raw_groups=\"$(id -G -- \"$user_name\" 2>/dev/null || true)\"", "  # filter out primary gid, deduplicate, keep numeric only", "  supp_groups=\"\"", "  for g in $raw_groups; do", "    case \"$g\" in", "      ''|*[!0-9]*) continue ;;", "    esac", "    if [ \"$g\" != \"$u_gid\" ]; then", "      already=0", "      for sg in $supp_groups; do", "        if [ \"$sg\" = \"$g\" ]; then", "          already=1", "          break", "        fi", "      done", "      if [ \"$already\" -eq 0 ]; then", "        supp_groups=\"${supp_groups}${supp_groups:+ }$g\"", "      fi", "    fi", "  done", "  printf '%s %s %s' \"$u_uid\" \"$u_gid\" \"$supp_groups\"", "}", "rewrite_group_add() {", "  p_name=\"$1\"", "  g_list=\"$2\"", "  compose_file=\"$3\"", "  [ -f \"$compose_file\" ] || die \"compose file missing at $compose_file\"", "  [ ! -L \"$compose_file\" ] || die \"compose file is a symlink\"", "  tmp_compose=\"$(mktemp \"${compose_file}.tmp.XXXXXX\")\"", "  awk -v param=\"$p_name\" -v g_list=\"$g_list\" '", "    BEGIN {", "      n = split(g_list, g_arr, \" \")", "    }", "    {", "      regex = \"^[ \\t]*# synopkgland:group_add \" param \"$\"", "      if ($0 ~ regex) {", "        match($0, /^[ \\t]*/)", "        indent = substr($0, RSTART, RLENGTH)", "        if (n > 0) {", "          print indent \"group_add:\"", "          for (i = 1; i <= n; i++) {", "            print indent \"  - ${\" param \"_GROUP_\" i \"}\"", "          }", "        }", "      } else {", "        print $0", "      }", "    }", "  ' \"$compose_file\" > \"$tmp_compose\" || die \"failed to rewrite group_add in $compose_file\"", "  mv \"$tmp_compose\" \"$compose_file\" || die \"failed to replace $compose_file\"", "}");
     }
@@ -752,6 +815,16 @@ function renderDynamicPreinstMaterializer(contract) {
         lines.push(`  if [ "\${${name}+x}" = x ]; then`, `    ${rawVar}="\${${name}}"`, '  elif [ "$STATUS" = "UPGRADE" ] && [ -f "$CANONICAL_ENV" ] && [ ! -L "$CANONICAL_ENV" ] && ' +
             `${rawVar}="$(read_env_value "$CANONICAL_ENV" "${name}")"; then`, "    :", "  else", `    die "missing required shared folder parameter ${name}"`, "  fi", `  case "$${rawVar}" in`, "    /*) " + pathVar + "=\"$" + rawVar + "\" ;;", "    *) " + pathVar + "=\"$(resolve_shared_folder \"$" + rawVar + "\")\" ;;", "  esac");
     }
+    const posixVars = [];
+    for (const { name } of posixAllSharesParams) {
+        const rawVar = "D54_RAW_POSIX_" + name;
+        const namesVar = "D54_POSIX_NAMES_" + name;
+        const pathsVar = "D54_POSIX_PATHS_" + name;
+        const countVar = "D54_POSIX_COUNT_" + name;
+        posixVars.push({ name, namesVar, pathsVar, countVar });
+        lines.push(`  if [ "\${${name}+x}" = x ]; then`, `    ${rawVar}="\${${name}}"`, '  elif [ "$STATUS" = "UPGRADE" ] && [ -f "$CANONICAL_ENV" ] && [ ! -L "$CANONICAL_ENV" ] && ' +
+            `${rawVar}="$(read_env_value "$CANONICAL_ENV" "${name}")"; then`, "    :", "  else", `    die "missing required POSIX all-shares parameter ${name}"`, "  fi", `  posix_info="$(resolve_posix_all_shares "$${rawVar}")"`, `  ${namesVar}="$(printf '%s\\n' "$posix_info" | sed -n '1p')"`, `  ${pathsVar}="$(printf '%s\\n' "$posix_info" | sed -n '2p')"`, `  ${countVar}="$(printf '%s\\n' "$posix_info" | sed -n '3p')"`, `  rewrite_posix_all_shares "${name}" "$${namesVar}" "$${pathsVar}" "$PROJECT/docker-compose.yml"`);
+    }
     if (dsmUserParam) {
         const name = dsmUserParam.name;
         const rawUserVar = "D54_RAW_USER_" + name;
@@ -770,6 +843,9 @@ function renderDynamicPreinstMaterializer(contract) {
     for (const { name, pathVar } of shareVars) {
         lines.push(`  append_env "${name}" "$${pathVar}" "string"`);
     }
+    for (const { name, namesVar, countVar } of posixVars) {
+        lines.push(`  append_env "${name}" "$${namesVar}" "string"`, `  append_env "${name}_COUNT" "$${countVar}" "string"`);
+    }
     if (dsmUserParam) {
         const name = dsmUserParam.name;
         const rawUserVar = "D54_RAW_USER_" + name;

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/compose/analyze.d.ts

@@ -57,6 +57,7 @@ export declare function validateComposeNumericCommandArgs(compose: ComposeDocume
 export interface HostBindContext {
     sharedFolderParams: ReadonlySet<string>;
     homesParams?: ReadonlySet<string>;
+    posixAllSharesParams?: ReadonlySet<string>;
     installParamNames: ReadonlySet<string>;
 }
 export declare function collectVolumeSourceInterpolations(compose: ComposeDocument): Set<string>;

package/dist/compose/analyze.js

@@ -190,6 +190,7 @@ const HEADLESS_PACKAGE_ONLY_PARAMETER_TYPES = new Set([
     "boolean",
     "shared_folder",
     "dsm_user",
+    "posix_all_shares",
 ]);
 /**
  * Chooses the local route D0 can safely emit. The first dynamic slice is
@@ -252,10 +253,14 @@ function collectRouteRejectErrors(contract, parsed, composeFile) {
     const installParams = collectInstallParameters(contract);
     const sharedFolderParams = new Set(installParams.filter(({ param }) => param.type === "shared_folder").map(({ name }) => name));
     const homesParams = new Set(installParams.filter(({ param }) => param.type === "homes").map(({ name }) => name));
+    const posixAllSharesParams = new Set(installParams
+        .filter(({ param }) => param.type === "posix_all_shares")
+        .map(({ name }) => name));
     const installParamNames = new Set(installParams.map(({ name }) => name));
     errors.push(...validateComposeHostBinds(compose, composeFile, {
         sharedFolderParams,
         homesParams,
+        posixAllSharesParams,
         installParamNames,
     }));
     return dedupeValidationErrors(errors);
@@ -296,7 +301,8 @@ function collectDynamicRouteError(contract, parsed, composeFile) {
         (param.type === "string" ||
             param.type === "boolean" ||
             param.type === "shared_folder" ||
-            param.type === "dsm_user"))
+            param.type === "dsm_user" ||
+            param.type === "posix_all_shares"))
         .map(({ name }) => name));
     const dsmUserParam = params.find(({ param }) => param.type === "dsm_user");
     const dsmUserDerivedNames = dsmUserParam
@@ -310,7 +316,8 @@ function collectDynamicRouteError(contract, parsed, composeFile) {
         (param.type !== "string" &&
             param.type !== "boolean" &&
             param.type !== "shared_folder" &&
-            param.type !== "dsm_user"));
+            param.type !== "dsm_user" &&
+            param.type !== "posix_all_shares"));
     const brokerOidcInterpolationNames = hasBrokerManagedOidc(contract)
         ? BROKER_OIDC_INTERPOLATION_VARS
         : [];
@@ -726,7 +733,8 @@ function classifyVolumeSource(compose, mount, namedVolumes, context, composeFile
         }
         if (PLATFORM_BIND_VARS.has(varName) ||
             context.sharedFolderParams.has(varName) ||
-            context.homesParams?.has(varName)) {
+            context.homesParams?.has(varName) ||
+            context.posixAllSharesParams?.has(varName)) {
             return null;
         }
         if (context.installParamNames.has(varName)) {

package/dist/contract/posix-all-shares.js

@@ -39,12 +39,12 @@ export function validatePosixAllSharesSources(compose, composeFile, declaredPara
             const path = `services.${serviceName}.volumes.${index}`;
             if (declaredParameters.has(name)) {
                 if (suffix !== "") {
-                    errors.push(makeError("COMPOSE_POSIX_ALL_SHARES_SUFFIX_FORBIDDEN", composeSpan(composeFile, 1, 1, path), `POSIX all-shares 參數「${name}」只能作為完整 volume source，不能附加子路徑。`, `請將 ${source} 改成 \${${name}}，並保留 Compose 的 container target；Share 名稱由 Broker 在安裝時展開。`));
+                    errors.push(makeError("COMPOSE_POSIX_ALL_SHARES_SUFFIX_FORBIDDEN", composeSpan(composeFile, 1, 1, path), `POSIX all-shares 參數「${name}」只能作為完整 volume source，不能附加子路徑。`, `請將 ${source} 改成 \${${name}}，並保留 Compose 的 container target；Share 名稱由 package-only preinst 在安裝時展開。`));
                 }
                 continue;
             }
             if (RESERVED_MARKER_NAMES.has(name)) {
-                errors.push(makeError("COMPOSE_POSIX_ALL_SHARES_UNDECLARED", composeSpan(composeFile, 1, 1, path), `Compose 使用了未宣告的 POSIX all-shares marker「${name}」。`, `請在 synology-app.yaml 宣告 install.${name}.type: ${POSIX_ALL_SHARES_TYPE}，並讓 Broker 以 DSM API 列出安裝當下的 Share。`));
+                errors.push(makeError("COMPOSE_POSIX_ALL_SHARES_UNDECLARED", composeSpan(composeFile, 1, 1, path), `Compose 使用了未宣告的 POSIX all-shares marker「${name}」。`, `請在 synology-app.yaml 宣告 install.${name}.type: ${POSIX_ALL_SHARES_TYPE}，並讓 wizard／CLI 取得安裝當下的 Share 清單。`));
             }
         }
     }

package/dist/contract/schema-validate.js

@@ -30,7 +30,7 @@ function mapSchemaError(error, contractFile, parsed) {
 }
 export function validateContractSchema(parsed, contractFile) {
     const validate = getValidator();
-    const data = schemaCompatibleContract(parsed.doc.toJSON());
+    const data = parsed.doc.toJSON();
     const valid = validate(data);
     if (valid) {
         return [];
@@ -48,28 +48,3 @@ export function validateContractSchema(parsed, contractFile) {
     }
     return result;
 }
-/**
- * Keep the published v1 schema's historical enum stable for older tooling,
- * while allowing the P4 contract extension to be validated by the same v1
- * object shape. The semantic validator and Broker retain the raw type.
- */
-function schemaCompatibleContract(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return value;
-    }
-    const contract = value;
-    const install = contract.install;
-    if (!install || typeof install !== "object" || Array.isArray(install)) {
-        return value;
-    }
-    for (const parameter of Object.values(install)) {
-        if (!parameter || typeof parameter !== "object" || Array.isArray(parameter)) {
-            continue;
-        }
-        const record = parameter;
-        if (record.type === "posix_all_shares") {
-            record.type = "homes";
-        }
-    }
-    return value;
-}

package/dist/contract/validate.js

@@ -51,16 +51,6 @@ export function validateContract(parsed, contractFile) {
     errors.push(...validateInstallParameters(parsed, contractFile));
     errors.push(...validatePosixAllShares(parsed, contractFile));
     errors.push(...validateWebLaunch(parsed, contractFile));
-    // The P4 worker cannot edit the shared host-bind analyzer. Its existing
-    // platform-resolved `homes` slot has the same analyzer semantics (declared
-    // interpolation is an allowed source and must be used). This normalization
-    // is local to the validation object; Broker and SPK generation read the raw
-    // YAML again and retain the actual posix_all_shares type.
-    for (const parameter of Object.values(contract.install ?? {})) {
-        if (parameter && isPosixAllSharesType(parameter.type)) {
-            parameter.type = "homes";
-        }
-    }
     return errors;
 }
 function validatePosixAllShares(parsed, contractFile) {

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,10 +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";
 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) {
     const contract = loadContract(project.contractPath).contract;
     const capabilities = ["identity"];
@@ -67,9 +69,34 @@ export async function deployProject(options) {
         return { ok: false, code: "CURATED_DEPLOY_REFUSED", message: CURATED_DEPLOY_REFUSED_MESSAGE };
     }
     const contract = loadContract(options.project.contractPath).contract;
+    const paramValues = { ...(options.paramValues ?? {}) };
+    const posixAllSharesNames = Object.entries(contract.install ?? {})
+        .filter(([, parameter]) => parameter?.type === "posix_all_shares")
+        .map(([name]) => name);
+    for (const name of posixAllSharesNames) {
+        if (Object.prototype.hasOwnProperty.call(paramValues, name)) {
+            continue;
+        }
+        let shareNames;
+        try {
+            shareNames = await options.host.listShareNames?.();
+        }
+        catch {
+            shareNames = undefined;
+        }
+        const names = (shareNames ?? []).map((value) => value.trim()).filter(Boolean);
+        if (names.length === 0) {
+            return {
+                ok: false,
+                code: POSIX_ALL_SHARES_LOOKUP_FAILED,
+                message: `無法用管理員 session 列出這台 NAS 的 Shared Folder，無法填入 POSIX all-shares 參數「${name}」。`,
+            };
+        }
+        paramValues[name] = names.join(",");
+    }
     const paramResolved = resolveInstallParameterExtraValues({
         contract,
-        provided: options.paramValues,
+        provided: paramValues,
     });
     if (!paramResolved.ok) {
         return { ok: false, code: paramResolved.code, message: paramResolved.message };
@@ -98,6 +125,24 @@ 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 extraValues = {
         ...paramResolved.extraValues,
         ...homesResolved.extraValues,
@@ -247,5 +292,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/param-values.js

@@ -1,4 +1,5 @@
 import { collectInstallParameters, stringViolations } from "../contract/load.js";
+import { isPosixAllSharesType } from "../contract/posix-all-shares.js";
 /**
  * Validate the local, non-secret values accepted by `deploy --param`.
  *
@@ -30,7 +31,7 @@ export function resolveInstallParameterExtraValues(input) {
             extraValues[name] = raw;
             continue;
         }
-        if (param.type !== "string") {
+        if (param.type !== "string" && !isPosixAllSharesType(param.type)) {
             return {
                 ok: false,
                 code: "DEPLOY_PARAM_TYPE_INVALID",

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/error-registry.js

@@ -83,7 +83,7 @@ export const ERROR_REGISTRY = {
     CONTRACT_POSIX_ALL_SHARES_VALUE_FORBIDDEN: {
         code: "CONTRACT_POSIX_ALL_SHARES_VALUE_FORBIDDEN",
         description: "POSIX all-shares 參數不得在契約中指定 default 或 NAS 實體路徑。",
-        suggestion: "請只宣告 type: posix_all_shares，讓 Broker 在安裝時用 DSM API 建立 Share snapshot。",
+        suggestion: "請只宣告 type: posix_all_shares，讓 wizard／CLI 在安裝時取得當下的 Share snapshot。",
     },
     DSM_USER_REQUIRED: {
         code: "DSM_USER_REQUIRED",
@@ -149,12 +149,12 @@ export const ERROR_REGISTRY = {
     COMPOSE_POSIX_ALL_SHARES_UNDECLARED: {
         code: "COMPOSE_POSIX_ALL_SHARES_UNDECLARED",
         description: "Compose 使用了未宣告的 POSIX all-shares marker。",
-        suggestion: "請宣告 type: posix_all_shares，讓 Broker 透過 DSM API 建立安裝當下的 Share snapshot。",
+        suggestion: "請宣告 type: posix_all_shares，讓 package-only wizard／CLI 取得安裝當下的 Share snapshot。",
     },
     COMPOSE_POSIX_ALL_SHARES_SUFFIX_FORBIDDEN: {
         code: "COMPOSE_POSIX_ALL_SHARES_SUFFIX_FORBIDDEN",
         description: "POSIX all-shares marker 不得附加 Share 子路徑。",
-        suggestion: "請只使用完整的 ${ALL_SHARES} source；每個 Share 的 container target 由 Broker 展開。",
+        suggestion: "請只使用完整的 ${ALL_SHARES} source；每個 Share 的 container target 由 package-only preinst 展開。",
     },
     COMPOSE_HOST_BIND_FORBIDDEN: {
         code: "COMPOSE_HOST_BIND_FORBIDDEN",
@@ -499,6 +499,11 @@ 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 仍是管理員的前提責任。",
+    },
     CURATED_DEPLOY_REFUSED: {
         code: "CURATED_DEPLOY_REFUSED",
         description: "目標 NAS 已持有 Curated App Package Attestation，禁止隨意覆蓋部署。",
@@ -529,6 +534,11 @@ export const ERROR_REGISTRY = {
         description: "deploy --param 的值不符合契約宣告的 string 或 boolean 型別。",
         suggestion: "string 請傳非空字串；boolean 請只傳 true 或 false。",
     },
+    DEPLOY_POSIX_ALL_SHARES_LOOKUP_FAILED: {
+        code: "DEPLOY_POSIX_ALL_SHARES_LOOKUP_FAILED",
+        description: "無法以管理員 session 列出部署當下的 Shared Folder 清單。",
+        suggestion: "請確認 DSM 管理員 session 可呼叫 SYNO.Core.Share list，或用 --param NAME=... 明確提供清單。",
+    },
     DSM_DEPENDENCY_CONFLICT: {
         code: "DSM_DEPENDENCY_CONFLICT",
         description: "DSM 複合安裝請求因執行中的依賴套件而拒絕。",

package/dist/host/dsm-client.js

@@ -4,7 +4,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { IDENTITY_CGI_PATH } from "./broker-paths.js";
 import { packageSourceOrigin } from "../deploy/catalog-publish.js";
-import { lookupSharePathWithSynoagentcli } from "./share-lookup.js";
+import { listShareNamesWithSynoagentcli, lookupSharePathWithSynoagentcli } from "./share-lookup.js";
+import { createSynoagentcliApiCall, fetchSharePermissions, fetchUserGroups, } from "./share-permission-lookup.js";
 import { dsmFetch } from "./dsm-http.js";
 import { installPackageFromCatalog, installPackageFromLocalSpk, uninstallPackageFromDsm, fetchInstalledPackageState, packageStateFromRecord, } from "./catalog-install.js";
 import { resolveHostCredentials } from "./credentials.js";
@@ -231,6 +232,15 @@ function createDsmNasHost(credentials, profileName) {
         async resolveSharePath(logicalName) {
             return lookupSharePathWithSynoagentcli(logicalName, profileName);
         },
+        async listShareNames() {
+            return listShareNamesWithSynoagentcli(profileName);
+        },
+        async listSharePermissions(logicalName) {
+            return fetchSharePermissions(logicalName, createSynoagentcliApiCall(profileName));
+        },
+        async listUserGroups(userName) {
+            return fetchUserGroups(userName, createSynoagentcliApiCall(profileName));
+        },
         async resolveHomesPath() {
             try {
                 const result = synoagentcli(["dsm", "control-panel", "user-group", "advanced", "get", "--section", "home"], profileName);

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

@@ -1,10 +1,26 @@
+import type { SharePermissionRow } from "./share-permission.js";
 import type { AttestationKind, HostInstallRecord, HostOidcCompatSettings, NasHost, PackageRoute } from "./types.js";
+export type SharePermissionRowInput = {
+    name: string;
+} & Partial<Omit<SharePermissionRow, "name">>;
 export interface FakeNasHostOptions {
     curated?: string[];
     dsmOrigin?: string;
     homesPath?: string;
     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[]>;
     installedEnv?: Record<string, Record<string, string>>;
     diagnostics?: {
         dsmResidue?: import("./types.js").DsmResidueInventory;

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";
@@ -8,6 +18,11 @@ export function createFakeNasHost(options = {}) {
     const installed = new Set();
     const openUrls = new Map();
     const shares = { ...(options.shares ?? {}) };
+    const shareNames = options.shareNames
+        ? [...options.shareNames]
+        : Object.keys(shares).length > 0
+            ? Object.keys(shares)
+            : ["docker", "home", "photo"];
     const installedEnv = Object.fromEntries(Object.entries(options.installedEnv ?? {}).map(([packageId, env]) => [packageId, { ...env }]));
     const host = {
         dsmOrigin,
@@ -24,6 +39,30 @@ export function createFakeNasHost(options = {}) {
         async resolveSharePath(logicalName) {
             return shares[logicalName];
         },
+        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];
+                },
+            }
+            : {}),
         async resolveHomesPath() {
             return options.homesPath;
         },

package/dist/host/share-lookup.d.ts

@@ -1,3 +1,5 @@
 export declare function shareRealPathFromEntry(entry: Record<string, unknown>, logicalName: string): string | undefined;
 export declare function findShareRealPath(payload: unknown, logicalName: string): string | undefined;
+export declare function findShareNames(payload: unknown): string[];
 export declare function lookupSharePathWithSynoagentcli(logicalName: string, profileName?: string): string | undefined;
+export declare function listShareNamesWithSynoagentcli(profileName?: string): string[];

package/dist/host/share-lookup.js

@@ -59,6 +59,16 @@ export function findShareRealPath(payload, logicalName) {
     }
     return undefined;
 }
+export function findShareNames(payload) {
+    const names = new Set();
+    for (const record of collectRecords(payload)) {
+        const name = record.name ?? record.share_name;
+        if (typeof name === "string" && name.trim() !== "") {
+            names.add(name.trim());
+        }
+    }
+    return [...names];
+}
 function synoagentcli(args, profileName) {
     const fullArgs = [...args];
     if (profileName) {
@@ -142,3 +152,10 @@ export function lookupSharePathWithSynoagentcli(logicalName, profileName) {
     }
     return lookupSharePathWithDsmHttp(logicalName, profileName);
 }
+export function listShareNamesWithSynoagentcli(profileName) {
+    const list = synoagentcli(["dsm", "control-panel", "shared-folder", "list"], profileName);
+    if (list.status !== 0) {
+        return [];
+    }
+    return findShareNames(parseJson(list.stdout));
+}

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;
+        }
+    };
+}

package/dist/host/share-permission.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared Folder permission pre-flight for the dynamic package-only route.
+ *
+ * Why this lives here and not in the SPK's preinst: preinst runs as the
+ * low-privilege package user, which cannot read ACL at all -- `synoacltool -get`
+ * answers `Access deny` and there is no CAP_SETUID to try the access as the
+ * selected user. The two places that *do* hold an administrator session are the
+ * install wizard and CLI `deploy`, so the check belongs to them. That makes it a
+ * pre-flight guard, not an enforcement gate: `deploy` can still be handed
+ * extra_values directly, and share permission can change after install.
+ *
+ * The rows are SYNO.Core.Share.Permission v1 output verbatim. Read the tests
+ * before changing the predicate: on vt-nas, `newadmin` has is_writable=false on
+ * its own row for `pkgland-p0b` and still writes there, because the
+ * `administrators` group row carries the grant. A user-row-only check rejects
+ * the only configuration with live proof behind it.
+ */
+export interface SharePermissionRow {
+    name: string;
+    is_admin: boolean;
+    is_writable: boolean;
+    is_readonly: boolean;
+    is_deny: boolean;
+    is_custom: boolean;
+}
+export type ShareAccess = "write" | "read" | "none" | "denied" | "unknown";
+export interface ShareAccessVerdict {
+    access: ShareAccess;
+    /** Which row granted access, as `user:<name>` or `group:<name>`. */
+    grantedBy?: string;
+    /** Which row denied access, as `user:<name>` or `group:<name>`. */
+    deniedBy?: string;
+    /** Why an `unknown` verdict could not be decided. */
+    reason?: "custom-acl" | "no-rows";
+}
+export interface ShareAccessInput {
+    userName: string;
+    /** Group names the user belongs to. Matched exactly -- no case folding. */
+    userGroups: readonly string[];
+    userRows: readonly SharePermissionRow[];
+    groupRows: readonly SharePermissionRow[];
+}
+export declare function evaluateShareAccess(input: ShareAccessInput): ShareAccessVerdict;

package/dist/host/share-permission.js

@@ -0,0 +1,59 @@
+/**
+ * Shared Folder permission pre-flight for the dynamic package-only route.
+ *
+ * Why this lives here and not in the SPK's preinst: preinst runs as the
+ * low-privilege package user, which cannot read ACL at all -- `synoacltool -get`
+ * answers `Access deny` and there is no CAP_SETUID to try the access as the
+ * selected user. The two places that *do* hold an administrator session are the
+ * install wizard and CLI `deploy`, so the check belongs to them. That makes it a
+ * pre-flight guard, not an enforcement gate: `deploy` can still be handed
+ * extra_values directly, and share permission can change after install.
+ *
+ * The rows are SYNO.Core.Share.Permission v1 output verbatim. Read the tests
+ * before changing the predicate: on vt-nas, `newadmin` has is_writable=false on
+ * its own row for `pkgland-p0b` and still writes there, because the
+ * `administrators` group row carries the grant. A user-row-only check rejects
+ * the only configuration with live proof behind it.
+ */
+function relevantRows(input) {
+    const groups = new Set(input.userGroups);
+    const candidates = [];
+    for (const row of input.userRows) {
+        if (row.name === input.userName) {
+            candidates.push({ row, label: `user:${row.name}` });
+        }
+    }
+    for (const row of input.groupRows) {
+        if (groups.has(row.name)) {
+            candidates.push({ row, label: `group:${row.name}` });
+        }
+    }
+    return candidates;
+}
+export function evaluateShareAccess(input) {
+    // An empty listing means the API answer was missing or truncated. Reading
+    // that as a denial would block installs on a transport error.
+    if (input.userRows.length === 0 && input.groupRows.length === 0) {
+        return { access: "unknown", reason: "no-rows" };
+    }
+    const candidates = relevantRows(input);
+    // Advanced/Windows ACL overrides share permission and only root-only
+    // synoacltool can read it, so any custom row in the deciding set makes the
+    // whole verdict inconclusive -- in both directions.
+    if (candidates.some(({ row }) => row.is_custom)) {
+        return { access: "unknown", reason: "custom-acl" };
+    }
+    const denied = candidates.find(({ row }) => row.is_deny);
+    if (denied) {
+        return { access: "denied", deniedBy: denied.label };
+    }
+    const writable = candidates.find(({ row }) => row.is_admin || row.is_writable);
+    if (writable) {
+        return { access: "write", grantedBy: writable.label };
+    }
+    const readable = candidates.find(({ row }) => row.is_readonly);
+    if (readable) {
+        return { access: "read", grantedBy: readable.label };
+    }
+    return { access: "none" };
+}

package/dist/host/types.d.ts

@@ -1,3 +1,4 @@
+import type { SharePermissionListing } from "../deploy/share-permission-preflight.js";
 import type { InstalledPackageState } from "./catalog-install.js";
 export type AttestationKind = "local" | "app-package" | "none";
 export type PackageRoute = "package-only" | "broker-installer" | "unknown";
@@ -76,7 +77,17 @@ export interface NasHost {
      * caller refuses instead of guessing.
      */
     getArchFamily?(): Promise<"x86_64" | "aarch64" | undefined>;
+    /** List the current logical Shared Folder names using an administrator session. */
+    listShareNames?(): Promise<string[]>;
     resolveSharePath?(logicalName: string): Promise<string | undefined>;
+    /**
+     * Read SYNO.Core.Share.Permission for one Share using an administrator
+     * session. Returns undefined when the host cannot answer -- callers must
+     * treat that as "cannot tell", never as a denial.
+     */
+    listSharePermissions?(logicalName: string): Promise<SharePermissionListing | undefined>;
+    /** Group names a DSM user belongs to, for resolving share permission. */
+    listUserGroups?(userName: string): Promise<string[] | 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>;

package/dist/validate.js

@@ -68,10 +68,14 @@ export function validateProject(project, options = {}) {
     const installParams = collectInstallParameters(parsed.contract);
     const sharedFolderParams = new Set(installParams.filter(({ param }) => param.type === "shared_folder").map(({ name }) => name));
     const homesParams = new Set(installParams.filter(({ param }) => param.type === "homes").map(({ name }) => name));
+    const posixAllSharesParams = new Set(installParams
+        .filter(({ param }) => param.type === "posix_all_shares")
+        .map(({ name }) => name));
     const installParamNames = new Set(installParams.map(({ name }) => name));
     errors.push(...validateComposeHostBinds(parsedCompose.compose, composeFile, {
         sharedFolderParams,
         homesParams,
+        posixAllSharesParams,
         installParamNames,
     }));
     if (typeof parsed.contract.adminport === "number") {
@@ -105,13 +109,14 @@ export function validateProject(project, options = {}) {
         ? { ...item, severity: (profile === "listing" ? "error" : "warning") }
         : item));
     for (const { name, param } of installParams) {
-        const referenced = param.type === "shared_folder" || param.type === "homes"
+        const referenced = param.type === "shared_folder" || param.type === "homes" || param.type === "posix_all_shares"
             ? volumeSourceVars.has(name)
             : interpolations.has(name);
         if ((param.type === "string" ||
             param.type === "boolean" ||
             param.type === "shared_folder" ||
-            param.type === "homes") &&
+            param.type === "homes" ||
+            param.type === "posix_all_shares") &&
             !referenced) {
             errors.push({
                 code: "INSTALL_PARAMETER_UNREFERENCED",

package/package.json

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

package/schema/synology-app.schema.json

@@ -59,7 +59,7 @@
         "properties": {
           "type": {
             "type": "string",
-            "enum": ["string", "boolean", "secret", "shared_folder", "dsm_user", "homes"]
+            "enum": ["string", "boolean", "secret", "shared_folder", "dsm_user", "homes", "posix_all_shares"]
           },
           "default": {},
           "generate": {

package/skills/reference/create.md

@@ -38,6 +38,10 @@ ports:
 
 包現成 Compose 時，先用 `inspect` 看原本的 volume mapping。容器路徑跟 Compose／映像的 upstream target 走，不要為了套平台範例改成 `/data`；只把 host source 換成 `${PARAM}`。原有的 upstream named volume 要保留在頂層 `volumes:`。需要既有 Share 時宣告 `install.<PARAM>.type: shared_folder`，管理員在安裝時選這台 NAS 的 Share。
 
+### `posix_all_shares`
+
+當 App 必須在安裝當下掛載這台 NAS 目前列出的每一個共用資料夾時，宣告 `install.<NAME>.type: posix_all_shares`，並把 `${NAME}` 作為完整 Compose volume source，例如 `${NAME}:/shares:ro`。Package Center wizard 會以 `SYNO.Core.Share.list` 的 multi-select 讓管理員再次確認；這是最大警告：容器可讀（或依 Compose 模式讀寫）所有列出的 Share，安裝後新建的共用資料夾不會自動加入，由管理員決定是否安裝。不要在契約或 Compose 寫 `/volume*`、domain、實體 path；`CLI deploy` 未給 `--param NAME=...` 時會用管理員 session 重新列出當下的 Share，preinst 只解析清單，不掃描檔案系統。
+
 ## 路線判準：零設定（Static Zero-Config）vs Dynamic vs Broker
 
 Syno Package Land 在打包 Compose App 時，依契約與 Compose 內容自動分類為不同路線：