@synopackageland/cli 0.41.3 → 0.41.5

package/dist/standalone/shared-folder.js

@@ -1,5 +1,7 @@
+import { DSM_LANGS, LOCALES } from "./i18n.js";
+import { existingShareValidator } from "../build-spk/share-validation.js";
 import { sharedFolderCombobox } from "../build-spk/share-combobox.js";
-import { renderWizardFiles } from "../build-spk/wizard-i18n.js";
+import { renderWizardFiles, translator } from "../build-spk/wizard-i18n.js";
 import { integrationWizardSteps } from "../build-spk/install-wizard.js";
 const FIELDS = new Set(["mode", "key", "name", "permission"]);
 const KEY = /^[a-z][a-z0-9_]{0,31}$/;
@@ -14,18 +16,18 @@ export function readSharedFolder(value, fail) {
         fail({ code: "STANDALONE_SHARED_FOLDER_INVALID", message: `install.sharedFolder ${why}` });
         return undefined;
     };
-    if (!isRecord(value) || Object.keys(value).some((key) => key !== "sharedFolder" && key !== "settings")) {
+    if (!isRecord(value) || Object.keys(value).some((key) => key !== "sharedFolder" && key !== "settings" && key !== "ports")) {
         return refuse(": only sharedFolder is allowed.");
     }
-    if (value.sharedFolder === undefined && value.settings !== undefined)
+    if (value.sharedFolder === undefined && (value.settings !== undefined || value.ports !== undefined))
         return undefined;
     const folder = value.sharedFolder;
     if (!isRecord(folder) || Object.keys(folder).some((key) => !FIELDS.has(key))) {
         return refuse(" accepts only mode, key, name and permission.");
     }
     const { mode, key, name, permission } = folder;
-    if (mode !== "select" && mode !== "create")
-        return refuse(" mode must be select or create.");
+    if (mode !== "select" && mode !== "create" && mode !== "dedicated")
+        return refuse(" mode must be dedicated, select or create.");
     if (permission !== "ro" && permission !== "rw")
         return refuse(" permission must be ro or rw.");
     if (typeof key !== "string" || !KEY.test(key) || RESERVED_KEY.test(key)) {
@@ -51,10 +53,9 @@ export function renderSharedFolderScript(pkg, folder) {
     const pick = folder.mode === "create"
         ? `name='${folder.name}'`
         : `name=""
-if [ "\${SYNOPKG_PKG_STATUS:-}" = "UPGRADE" ] && ! change_enabled "\${CHANGE_${key}:-}"; then
-  exit 0
-fi
-name="\${${key}:-}"
+${folder.mode === "dedicated" ? `if [ "\${SYNOPKG_PKG_STATUS:-}" = "UPGRADE" ] && [ "\${${key}+x}" != x ]; then exit 0; fi` : ""}
+${folder.mode === "select" ? `if [ "\${SYNOPKG_PKG_STATUS:-}" = "UPGRADE" ] && ! change_enabled "\${CHANGE_${key}:-}"; then\n  exit 0\nfi` : ""}
+name="\${${key}:-${folder.mode === 'dedicated' ? folder.name : ''}}"
 case "$name" in
   ''|*/*|*..*|@*|.*|*[[:cntrl:]]*|*'"'*|*'\\'*) echo "invalid shared folder name for ${key}" >&2; exit 1 ;;
 esac`;
@@ -79,14 +80,26 @@ exit 0
 function intro(t, pkg, folder) {
     const permission = t(`nativeShare.permission.${folder.permission}`);
     return {
-        desc: folder.mode === "create"
+        desc: folder.mode !== "select"
             ? t("nativeShare.createIntro", { name: folder.name, permission })
             : t("nativeShare.selectIntro", { account: pkg, permission }),
     };
 }
 /** Install: the share picker (select) or a note (create). */
 function installItems(t, pkg, folder) {
-    return folder.mode === "create" ? [intro(t, pkg, folder)] : [intro(t, pkg, folder), sharedFolderCombobox(t, folder.key)];
+    if (folder.mode === "create")
+        return [intro(t, pkg, folder)];
+    const picker = sharedFolderCombobox(t, folder.key);
+    const field = picker.subitems[0];
+    field.defaultValue = folder.mode === "dedicated" ? folder.name : "";
+    if (folder.mode === "dedicated") {
+        field.editable = true;
+        field.forceSelection = false;
+    }
+    field.validator = { allowBlank: folder.mode === "dedicated", fn: existingShareValidator(pkg, folder.permission, t("nativeShare.selectionInvalid"), folder.mode === "dedicated", folder.name) };
+    if (folder.mode === "dedicated")
+        picker.desc = t("nativeShare.optionalExisting", { name: folder.name });
+    return [intro(t, pkg, folder), picker];
 }
 /**
  * Upgrade: DSM prefills the first share, so a checked `CHANGE_<key>` box is what
@@ -95,8 +108,15 @@ function installItems(t, pkg, folder) {
 function upgradeItems(t, pkg, folder) {
     if (folder.mode === "create")
         return [intro(t, pkg, folder)];
+    if (folder.mode === "dedicated") {
+        const items = installItems(t, pkg, folder);
+        const field = items[1].subitems[0];
+        field.defaultValue = "";
+        field.validator = { allowBlank: false, fn: existingShareValidator(pkg, folder.permission, t("nativeShare.selectionInvalid"), false, folder.name) };
+        return items;
+    }
     const label = t("label.sharedFolder");
-    const picker = sharedFolderCombobox(t, folder.key);
+    const picker = installItems(t, pkg, folder)[1];
     const [subitem] = picker.subitems;
     const { defaultValue: _unused, ...blankable } = subitem;
     return [
@@ -106,7 +126,7 @@ function upgradeItems(t, pkg, folder) {
             desc: t("upgrade.changeDesc", { label }),
             subitems: [{ key: `CHANGE_${folder.key}`, desc: t("upgrade.changeSub", { label }), defaultValue: false }],
         },
-        { ...picker, desc: t("upgrade.reuseDesc", { desc: String(picker.desc) }), subitems: [{ ...blankable, validator: { allowBlank: true } }] },
+        { ...picker, desc: t("upgrade.reuseDesc", { desc: String(picker.desc) }), subitems: [{ ...blankable, validator: { allowBlank: true, fn: existingShareValidator(pkg, folder.permission, t("nativeShare.selectionInvalid"), true) } }] },
     ];
 }
 /** `install_uifile` and `upgrade_uifile`, English plus one file per DSM language. */
@@ -122,7 +142,7 @@ export function sharedFolderInstallSteps(pkg, folder) {
 }
 /** The upgrade wizard files that let the administrator keep or change the shared folder. */
 export function renderSharedFolderUpgradeWizardFiles(pkg, folder) {
-    return renderWizardFiles("upgrade_uifile", t => [{ step_title: t("upgrade.step"), items: upgradeItems(t, pkg, folder) }]);
+    return renderUpgradeWizardFiles(pkg, folder);
 }
 /**
  * The upgrade wizard: the shared folder choice, then the service callbacks an
@@ -131,14 +151,29 @@ export function renderSharedFolderUpgradeWizardFiles(pkg, folder) {
 export function renderUpgradeWizardFiles(pkg, folder, integrations = []) {
     if (!folder && !integrations.length)
         return {};
-    return renderWizardFiles("upgrade_uifile", t => [
+    const files = renderWizardFiles("upgrade_uifile", t => [
         ...(folder ? [{ step_title: t("upgrade.step"), items: upgradeItems(t, pkg, folder) }] : []),
         ...integrationWizardSteps(t, integrations),
     ]);
+    if (folder?.mode === "dedicated") {
+        for (const locale of LOCALES) {
+            const t = translator(locale);
+            const steps = [{ step_title: t("upgrade.step"), items: upgradeItems(t, pkg, folder) }, ...integrationWizardSteps(t, integrations)];
+            const field = steps[0].items[1].subitems[0];
+            field.defaultValue = "__SYNOPKGLAND_RETAINED_SHARE__";
+            const invalid = JSON.stringify(steps, null, 2).replace('"__SYNOPKGLAND_RETAINED_SHARE__"', '""');
+            field.validator = { allowBlank: true, fn: existingShareValidator(pkg, folder.permission, t("nativeShare.selectionInvalid"), true, folder.name) };
+            const retained = JSON.stringify(steps, null, 2);
+            const fresh = JSON.stringify([{ step_title: t("upgrade.step"), items: installItems(t, pkg, folder) }, ...integrationWizardSteps(t, integrations)], null, 2);
+            const name = locale === "en" ? "upgrade_uifile.sh" : `upgrade_uifile_${DSM_LANGS[locale]}.sh`;
+            files[name] = dedicatedUpgradeScript(pkg, folder.key, retained, fresh, invalid);
+        }
+    }
+    return files;
 }
 /** `conf/resource` `data-share` entry: create mode only; DSM never deletes the share on uninstall. */
 export function sharedFolderResource(pkg, folder) {
-    if (folder.mode !== "create")
+    if (folder.mode === "select")
         return undefined;
     return { shares: [{ name: folder.name, permission: { [folder.permission]: [pkg] } }] };
 }
@@ -154,3 +189,27 @@ export function recoverSharedFolder(postinst) {
         return undefined;
     }
 }
+function dedicatedUpgradeScript(pkg, key, retained, fresh, invalid) {
+    return `#!/bin/sh
+set -eu
+config="\${SYNOPKG_PKGVAR:-/var/packages/${pkg}/var}/config.json"
+[ -z "\${SYNOPKG_TEMP_LOGFILE:-}" ] || exec > "$SYNOPKG_TEMP_LOGFILE"
+if [ ! -e "$config" ]; then
+  cat <<'SYNOPKGLAND_WIZARD'
+${fresh}
+SYNOPKGLAND_WIZARD
+else
+  name=$(sed -n 's/^{{SCHEMA_PREFIX}}${key}{{NAME_PREFIX}}\\([^"\\\\]*\\){{SUFFIX}}$/\\1/p' "$config")
+  case "$name" in ''|*/*|*..*|@*|.*|*[[:cntrl:]]*|*'"'*|*'\\'*) name='' ;; esac
+  if [ -z "$name" ]; then
+    cat <<'SYNOPKGLAND_WIZARD'
+${invalid}
+SYNOPKGLAND_WIZARD
+  else
+    cat <<'SYNOPKGLAND_WIZARD' | sed "s/__SYNOPKGLAND_RETAINED_SHARE__/$name/"
+${retained}
+SYNOPKGLAND_WIZARD
+  fi
+fi
+`.replace('{{SCHEMA_PREFIX}}', '{"schema":1,"shared_folders":{"').replace('{{NAME_PREFIX}}', '":"').replace('{{SUFFIX}}', '"}}');
+}

package/dist/standalone/spk.js

@@ -1,3 +1,4 @@
+import { portDefaults, portInstallSteps, writePortPayload } from "./install-ports.js";
 import { packageDependencies, dependencyInfo } from "./package-dependencies.js";
 import { settingsInstallSteps, settingsConfig } from './install-settings.js';
 import { backupConfig, backupHookProblem, backupRecord, renderBackupScripts, BACKUP_PAYLOAD_DIR, BACKUP_SCRIPTS_DIR, BACKUP_SCRIPT_MODES } from './hyper-backup.js';
@@ -32,7 +33,7 @@ import { copyAppTree } from "./bridge-app.js";
 import { isBridgeBackend } from "./bridge-backend.js";
 import { hostScriptName, renderHostAdapterScript } from "./host-adapter.js";
 import { writeComposePayload } from "./compose.js";
-import { copyDaemonPayload, daemonSdkVersion } from "./daemon.js";
+import { daemonConfig, copyDaemonPayload, daemonSdkVersion } from "./daemon.js";
 import { DAEMON_INGRESS_CONFIG, renderDaemonIngressConfig } from "./daemon-ingress.js";
 import { gatewayCgiPaths, gatewayExternalAccess, GATEWAY_CONFIG_PATH, GATEWAY_EXEC, identityGatewayConfig, identityGatewayDeclaration, } from "./identity-gateway.js";
 import { BACKGROUND_UNIT_DIR, BACKGROUND_WORKER_PAYLOAD, backgroundUnitName, renderBackgroundUnit, BRIDGE_WORKER_ARGS, } from "./background.js";
@@ -219,13 +220,14 @@ export async function assembleStandaloneSpk(options) {
                 chmodSync(join(target, "storage-init"), EXEC_MODE);
             }
         }
-        if (manifest.installSettings) {
+        if (manifest.installSettings || manifest.installPorts) {
             if (!options.installSettingsControl)
                 throw new StandaloneBuildError('SDK_INSTALL_SETTINGS_BUILD_FAILED', 'SDK settings controller required.');
             const target = join(staging, 'package/install');
             mkdirSync(target, { recursive: true });
             copyExecutable(options.installSettingsControl, join(target, 'control'));
-            writeFile(join(target, 'settings.json'), JSON.stringify(settingsConfig(manifest), null, 2) + '\n');
+            if (manifest.installSettings)
+                writeFile(join(target, 'settings.json'), JSON.stringify(settingsConfig(manifest), null, 2) + '\n');
         }
         const backup = options.appBackupControl ? manifest.hyperBackup : undefined;
         if (backup) {
@@ -235,6 +237,14 @@ export async function assembleStandaloneSpk(options) {
             copyExecutable(options.appBackupControl, join(staging, "package", BACKUP_PAYLOAD_DIR, "control"));
             writeFile(join(staging, "package", BACKUP_PAYLOAD_DIR, "config.json"), backupConfig(manifest.package, backup));
         }
+        if (manifest.installPorts)
+            writePortPayload(manifest, join(staging, 'package'), variant => ({
+                'sso/gateway.json': identityGatewayConfig(variant),
+                ...(nativeGatewaySupported(variant) ? { [NATIVE_GATEWAY_CONFIG]: renderNativeGatewayConfig(variant) } : {}),
+                ...(hasSdkWindow(variant) ? { ['ui/' + windowScriptName(variant)]: renderWindowScript(variant, assetVersion, icons, options.portalText, moduleVersion) } : {}),
+                ...(variant.daemon || variant.compose ? { 'daemon/config.json': daemonConfig(variant) } : {}),
+                ...(variant.installSettings ? { 'install/settings.json': JSON.stringify(settingsConfig(variant), null, 2) + '\n' } : {}),
+            }));
         const packageTgz = join(staging, "package.tgz");
         await createReproducibleTar(join(staging, "package"), packageTgz, {
             gzip: true,
@@ -248,6 +258,7 @@ export async function assembleStandaloneSpk(options) {
             dependencies: packageDependencies(manifest),
             ...(moduleVersion ? { ui_module: moduleVersion } : {}),
             ...(manifest.installSettings ? { installSettings: manifest.installSettings } : {}),
+            ...(manifest.installPorts ? { installPorts: portDefaults(manifest) } : {}),
             ...(backup ? { hyperBackup: backupRecord(backup) } : {}),
             ...(manifest.integrations ? { integrations: manifest.integrations } : {}),
             ...(manifest.lifecycleTimeouts ? { lifecycleTimeouts: manifest.lifecycleTimeouts } : {}),
@@ -313,7 +324,7 @@ export async function assembleStandaloneSpk(options) {
             : folder
                 ? sharedFolderInstallSteps(manifest.package, folder)
                 : renderNativeInstallWizard;
-        const install = renderInstallWizardFiles(manifest.package, (t) => [...steps(t), ...settingsInstallSteps(manifest.installSettings)(t), ...(portal ? [renderPortalWizardStep(t, portal.alias)] : []), ...integrationWizardSteps(t, manifest.integrations)]);
+        const install = renderInstallWizardFiles(manifest.package, (t) => [...steps(t), ...portInstallSteps(manifest)(t), ...settingsInstallSteps(manifest.installSettings, manifest.identityGateway?.listen.https, manifest.installPorts ? manifest.package : undefined)(t), ...(portal ? [renderPortalWizardStep(t, portal.alias)] : []), ...integrationWizardSteps(t, manifest.integrations)]);
         writeWizardUiFiles(staging, {
             ...install.static,
             ...install.dynamic,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.41.3",
+  "version": "0.41.5",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "~0.35.2",
+    "@synopackageland/templates": "~0.35.3",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-The CLI installs templates through `~0.35.2`. A templates patch needs only a
+The CLI installs templates through `~0.35.3`. A templates patch needs only a
 templates release; npm install/update selects a patch in that minor line. The CLI
 uses the locally installed templates and reads their SDK pin for defaults; it
 never downloads templates at runtime. Preserve the lockfile and use `npm ci` for
@@ -16,6 +16,8 @@ The CLI verifies bytes before packaging and never fetches a manifest at NAS runt
 Unsupported formats require a CLI update; invalid manifests fail closed. Existing
 SDK 0.26.0/0.27.0 use the frozen legacy inventory.
 
+For Apps with data folders or gateway listeners, read [reference/install.md](reference/install.md). Default to an App-named dedicated DSM data share and installer-selected ports. Existing-folder access, port availability and required HTTPS origins must pass localized wizard validation before Next; upgrades retain port selections.
+
 All CLI NAS requests share one connection path. NAS certificates are accepted by default, including self-signed, wrong-name and expired certificates. A changed certificate warns once, updates its displayed SHA-256 and continues. `host add --strict-tls` stores strict verification; `--strict-tls` or `--ca <file>` on a command opts in for that command. Read [reference/host-install.md](reference/host-install.md) for host trust and error codes.
 
 Before releasing an executor App, read [reference/approval-upgrades.md](reference/approval-upgrades.md). Run build/inspect with the previous released SPK as `--baseline` and include the approval difference in release notes. Without a comparable baseline, retention is unknown.
@@ -24,7 +26,7 @@ Use this guide to initialize, build and inspect own applications or upstream OSS
 
 For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.3 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
 
-Use SDK/App 0.38.1 and CLI 0.41.3 for App entry enforcement. Declare every App method
+Use SDK/App 0.38.2 and CLI 0.41.5 for App entry enforcement. Declare every App method
 in the permissions table; dynamic names and unregistered HTTP dispatchers are rejected.
 Use fixed SDK routes and `identity_gateway.upstream_auth_paths` for client API
 paths that rely on upstream authentication. Read
@@ -41,7 +43,7 @@ cannot upgrade a connection; use an existing upgrade-capable deployment
 transport. The audit follows each configured Go binary's Linux import graph,
 including declared workers; unshipped dev commands are excluded.
 
-SDK/App 0.38.1 allows 300 seconds for requests by default, with the browser
+SDK/App 0.38.2 allows 300 seconds for requests by default, with the browser
 waiting 302 seconds. Explicit budgets and earlier parent deadlines still win.
 For long work, use existing independent workers with prompt job admission,
 progress and authorized status/result polling by the original ID. A timed-out

package/skills/reference/compose.md

@@ -15,6 +15,9 @@ maintainer: Example
 os_min_ver: "7.2.1-69057"
 arches: [x86_64, aarch64]
 capabilities: {}
+install:
+  ports: true
+  sharedFolder: {mode: dedicated, key: data, name: MediaApp, permission: rw}
 compose:
   files: [compose.yaml, site.yaml]
   env_files: [.env]
@@ -23,22 +26,22 @@ compose:
   network: {egress: isolated}
   # Private package binds are rejected by DSM build; keep compatible upstream named volumes.
 identity_gateway:
-  sdk: 0.17.3
+  sdk: 0.38.2
   mode: none
   access: dsm-users
   listen: {http: 28000}
 ui: {launch: new-page}
 ```
 
-No backend, dummy CGI, UI directory or helper payload is required. Omit `web`
-and `identity_gateway` for headless projects. Optional `compose.helpers` names
+No backend, dummy CGI, UI directory or helper payload is required. Omit `web`,
+`identity_gateway` and `install.ports` for headless projects. Optional `compose.helpers` names
 architecture-specific native payloads for token/account adapters. All lifecycle
 scripts run as the package account; containers are managed by Container Manager.
 
 For external access, pin both `compose.sdk` and `identity_gateway.sdk` to
-0.29.0 or later and use the gateway's
+0.38.2 and use the gateway's
 [`external_access` policy and DSM settings entry](identity-gateway.md#external-access).
-There are no installation-wizard URL fields or post-install state initialization.
+Declare required HTTPS origins through `install.settings`; wizard validation checks the selected HTTPS port before Next. See [install.md](install.md).
 Manual URL configuration does not require Connect. The SDK resolves the public
 origin for Compose; restart the App after changing an origin used by its
 environment or a generated private snapshot.
@@ -137,12 +140,12 @@ modification and deletion. DSM identity/account bridge and file authority are
 separate features. Per-DSM-user filesystem access requires a File Station session
 or Broker Adapter; it is outside this change and cannot be obtained through a mount.
 
-For one existing Shared Folder, reuse the native install/upgrade wizard:
+For a data Shared Folder, default to the native dedicated share; the wizard also allows a validated existing share:
 
 ```yaml
 capabilities: {composeMounts: true}
 install:
-  sharedFolder: {mode: select, key: media, permission: ro}
+  sharedFolder: {mode: dedicated, key: media, name: MediaApp, permission: ro}
 compose:
   shares:
     media:
@@ -152,19 +155,20 @@ compose:
 ```
 
 The share key and permission must match `install.sharedFolder` exactly. This
-route supports `mode: select`; `create` resource ordering is not supported.
+route supports `mode: dedicated` and `mode: select`; `create` resource ordering is not supported.
 The package-account preinst resolves the chosen name on `/volumeN` and writes
 only the fixed source placeholder into the worker's private `.env`. Missing,
 ambiguous or symlinked sources fail installation. Host paths are never wizard
 answers. Every mounted service uses the fixed package UID:GID, drops all Linux
 capabilities and has no-new-privileges. Container-root cannot mount Shares.
 
-**Selecting an existing share does not grant permission.** An administrator must
-grant the package account access in **Control Panel > Shared Folder > Edit >
-Permissions > System internal user**. Until then, container file operations fail
-under the kernel's ACL checks. No root helper, ACL writer or Docker socket is
-given to the App. Grant directly to the package account; supplementary DSM groups
-are not added to the container. See the SDK Shared Folder permission guide.
+DSM creates the dedicated App-named share and grants exactly the declared RO/RW
+through `data-share`; the installer accepts its default without a folder choice.
+An existing share must pass the localized field check for supported folder type
+and package-account access before Next. Unknown access is refused. The SDK
+checks kernel access before startup and reports the share, required permission
+and recovery action if access has been revoked. No App root process or manual
+ACL writer is used. See [install.md](install.md).
 
 The upgrade wizard keeps the saved name unless its change checkbox is selected.
 CLI deployment uses `--param media=Media` on first install, and

package/skills/reference/deploy.md

@@ -9,7 +9,7 @@ NAS HTTPS accepts any certificate by default. A changed leaf warns and updates t
 3. Review `synopkgland deploy --dry-run --arch x86_64`, which does not connect to a NAS.
 4. Only when installation is authorized, run `synopkgland deploy --host <profile>`.
 
-Deployment uploads directly to DSM. It does not publish artifacts. Compose uses schema-2 differences and fixed package identity. For `compose.shares` with `select: install`, use matching `install.sharedFolder: {mode: select, key: media, permission: ro}` and pass `--param media=Media`. Upgrade keeps the selection unless `--param CHANGE_media=true --param media=OtherMedia` is provided. An administrator grants the fixed package account access through DSM; selection is not a grant. Dynamic admin-after-install protected ACL/project control remains blocked. A user destination grant never activates a package mount. See compose.md and its device acceptance blockers.
+Deployment uploads directly to DSM. It does not publish artifacts. Compose uses schema-2 differences and fixed package identity. For `compose.shares` with `select: install`, default to matching `install.sharedFolder: {mode: dedicated, name: MyApp, key: media, permission: ro}`. DSM creates and grants the dedicated share; existing selections must pass wizard validation before Next. Upgrade keeps the selection unless `--param CHANGE_media=true --param media=OtherMedia` is provided. Use `install.ports: true` for configurable gateway listeners and `--param pkgwizard_port_gateway_https=29443` for first-install automation; upgrade keeps the retained ports, and changing ports uses reinstall. See [install.md](install.md). Dynamic admin-after-install protected ACL/project control remains blocked. A user destination grant never activates a package mount. See compose.md and its device acceptance blockers.
 
 For native-go root-ops, approve fixed operations in DSM after installation. Updates that change the task text require fresh approval. Uninstall removes the executor tasks, the App's Application Privileges rules and a stale portal alias itself. Never delete installed packages or data as part of a code cleanup.
 

package/skills/reference/files.md

@@ -87,7 +87,7 @@ sweep forward the cancel instead of admitting it.
 
 容器使用固定 DSM run-as 使用者與掛載，不代表瀏覽器本人 ACL。容器路徑依 Compose／映像的 upstream target，保留 target、ro/rw，只替換 host source；管理員在安裝時選擇 Share（共用資料夾）。不要對既有資料 chown。App Data 使用 package var；共用資料夾與 named volume 分別備份。`posix_all_shares` 僅為部署時快照，不會自動加入新資料夾。
 
-`install.sharedFolder` 使用套件帳號：select 模式安裝後可能須管理員手動授予權限，create 由 DSM data-share 建立；都不是逐使用者 session access。移除不刪共用資料夾。Delete App Data 不是完整清理證明，須讀回殘留。
+`install.sharedFolder` 預設使用 `mode: dedicated` 與 app 名稱，由 DSM data-share 建立並賦予套件帳號宣告的 RO/RW。使用者可選現有資料夾，但權限與類型必須在 wizard 當步驗證，不可等到啟動後才手動修復。這不是逐使用者 session access；詳見 [install.md](install.md)。移除不刪共用資料夾。Delete App Data 不是完整清理證明，須讀回殘留。
 
 
 ### Install-selected scope and the destination API

package/skills/reference/identity-gateway.md

@@ -233,8 +233,10 @@ App's responsibility.
 An upstream with its own OIDC login can opt into a generic browser bridge:
 
 ```yaml
+install:
+  ports: true
 identity_gateway:
-  sdk: 0.18.0
+  sdk: 0.38.2
   mode: oidc
   access: dsm-admins
   upstream: 8000
@@ -290,3 +292,5 @@ produce an App session, or unlock encrypted data. HTTPS and App-specific
 fragment/query semantics still require deployment acceptance.
 
 Single-origin Apps require SDK 0.30.0 or later. Their `manual_origin` may include an explicit HTTPS port (for example, `https://example.ts.net:29443`). The DSM launcher resolves the destination for the provider used to open DSM, probes `/_spl/ping` for up to eight seconds, and offers **Open anyway** if the probe fails. A single-origin App always uses its configured primary origin. Other Apps and the `external-origin` install setting continue to require HTTPS DNS origins on port 443.
+
+Configurable gateway ports use `install.ports: true`; read [install.md](install.md) for field validation, retained selections and upstream runtime bindings. Do not repeat the manifest defaults in App configuration.

package/skills/reference/install.md

@@ -0,0 +1,41 @@
+# Native installation settings
+
+Use SDK/App 0.38.2, CLI 0.41.5 and templates 0.35.3. Configure installation through the manifest and generated wizard; do not add App ACL writers, root hooks or independent port state.
+
+```yaml
+install:
+  ports: true
+  sharedFolder:
+    mode: dedicated
+    key: data
+    name: MyApp
+    permission: rw
+identity_gateway:
+  sdk: 0.38.2
+  listen: {https: 28443}
+```
+
+For every App needing shared data, name the dedicated share after the package. DSM's `data-share` resource creates it and grants the package account exactly RO or RW. The wizard defaults to that share. An optional existing share must pass folder-type and package-account access validation before Next; unknown access is refused. Runtime access checks fail promptly with the share name, required access and recovery action. Shared data is retained on uninstall.
+
+Port fields default to declared gateway HTTP/HTTPS and local OIDC listener ports. Validation refuses noncanonical numbers, values outside 1024–65535, reserved DSM/discovery ports, duplicates and conflicts from DSM's `SYNO.Core.Service.PortInfo` inventory. Missing or malformed inventory blocks Next. The package-account controller repeats the native service conflict check and materializes gateway, nginx, launcher, daemon and `.sc` port-config data from the selected values.
+
+Native subprocesses and Compose `.env` receive `SYNOPKGLAND_PORT_GATEWAY_HTTP`, `SYNOPKGLAND_PORT_GATEWAY_HTTPS` and, when declared, `SYNOPKGLAND_PORT_OIDC_ISSUER`. Go Apps can read `installsettings.PortValues(payloadRoot)`. Bind upstream public-port configuration declaratively:
+
+```yaml
+compose:
+  services:
+    web:
+      storage_init:
+        directories: [{base: /data, path: app}]
+        runtime:
+          environment:
+            PUBLIC_PORT: {port: gateway_https}
+```
+
+Existing runtime file templates can use the same variable in the App's own configuration. Container-internal listener and fixed discovery ports keep their upstream contract. Do not hard-code the selected host port elsewhere.
+
+Upgrade retains the saved ports and ignores submitted replacements. Reinstall to change ports, then re-enter any required HTTPS origin with its new HTTPS port. First-install CLI automation accepts `--param pkgwizard_port_gateway_https=29443`; programmatic upgrade refuses port changes. Omit `install.ports` when no identity gateway is declared.
+
+Use `install.settings` with `type: https-origin`, a localized label and explicit `required: true` for an origin needed by the App. The wizard blocks Next for missing or malformed values and checks the selected HTTPS port. Runtime validation repeats the check.
+
+DSM references: [data-share](https://help.synology.com/developer-guide/resource_acquisition/data_share.html), [service ports](https://help.synology.com/developer-guide/integrate_dsm/ports.html), [port-config](https://help.synology.com/developer-guide/resource_acquisition/port_config.html).