@synopackageland/cli 0.8.0 → 0.9.1

package/dist/build-spk/wizard-messages.d.ts

@@ -384,6 +384,39 @@ export declare const WIZARD_MESSAGES: {
         es: string;
         it: string;
     };
+    "uninstall.appPrivilege": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "uninstall.appPrivilege.auto": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
+    "uninstall.portal.auto": {
+        en: string;
+        "zh-TW": string;
+        "zh-CN": string;
+        ja: string;
+        ko: string;
+        de: string;
+        fr: string;
+        es: string;
+        it: string;
+    };
     "uninstall.keep.native": {
         en: string;
         "zh-TW": string;

package/dist/build-spk/wizard-messages.js

@@ -384,6 +384,39 @@ export const WIZARD_MESSAGES = {
         "es": "La desinstalación elimina de forma asíncrona en segundo plano el runtime executor, el socket y las delegaciones. Borra las tareas «{package} executor boot» y «{package} executor control» tras verificar el nombre exacto, el propietario root y el resumen del script. El buzón purge de preuninst solicita la limpieza inmediatamente; esta se completa de forma asíncrona. El tiempo de espera agotado no bloquea la desinstalación. Como respaldo, el monitor pausa el servicio si falta el directorio del paquete o su identidad INFO y limpia solo tras 10 minutos de ausencia continua. Su reaparición reinicia el temporizador. Si el proceso no existe, la limpieza espera al próximo arranque. Las tareas modificadas o no verificables se conservan para revisión del administrador en Panel de control > Programador de tareas.",
         "it": "La disinstallazione elimina in modo asincrono in background runtime executor, socket e deleghe. Le attività “{package} executor boot” e “{package} executor control” vengono eliminate dopo aver verificato nome esatto, proprietario root e digest dello script. La mailbox purge di preuninst richiede subito la pulizia, che termina in modo asincrono. Un timeout non blocca la disinstallazione. Come riserva, il monitor sospende il servizio se mancano la directory del pacchetto o la sua identità INFO e pulisce solo dopo 10 minuti di assenza continua. La ricomparsa azzera il timer. Se il processo è assente, la pulizia attende il prossimo avvio. Le attività modificate o non verificabili restano da esaminare da un amministratore in Pannello di controllo > Utilità di pianificazione."
     },
+    "uninstall.appPrivilege": {
+        en: "DSM keeps the rules of {package} in Control Panel > Application Privileges after uninstall, and a later install under the same name applies them again. If the app will not be reinstalled, an administrator can remove its rules there.",
+        "zh-TW": "解除安裝後，DSM 會保留 {package} 在「控制台」>「應用程式權限」中的規則；之後以相同名稱安裝時會再次套用。若不再安裝此 App，管理員可在該處移除它的規則。",
+        "zh-CN": "卸载后，DSM 会保留 {package} 在“控制面板”>“应用程序权限”中的规则；之后以相同名称安装时会再次应用。如果不再安装此应用，管理员可在该处删除它的规则。",
+        ja: "アンインストール後も DSM は [コントロール パネル] > [アプリケーション権限] にある {package} のルールを保持し、同じ名前で再インストールすると再び適用します。再インストールしない場合は、管理者がそこでルールを削除できます。",
+        ko: "제거 후에도 DSM은 제어판 > 응용 프로그램 권한에 있는 {package}의 규칙을 유지하며, 같은 이름으로 다시 설치하면 다시 적용합니다. 다시 설치하지 않을 경우 관리자가 그곳에서 규칙을 삭제할 수 있습니다.",
+        de: "DSM behält die Regeln von {package} unter Systemsteuerung > Anwendungsberechtigungen nach der Deinstallation bei und wendet sie bei einer späteren Installation unter demselben Namen erneut an. Wird die App nicht erneut installiert, kann ein Administrator die Regeln dort entfernen.",
+        fr: "DSM conserve les règles de {package} dans Panneau de configuration > Privilèges d’application après la désinstallation et les applique de nouveau lors d’une installation ultérieure sous le même nom. Si l’application ne sera pas réinstallée, un administrateur peut y supprimer ses règles.",
+        es: "DSM conserva las reglas de {package} en Panel de control > Privilegios de aplicaciones tras la desinstalación y las aplica de nuevo en una instalación posterior con el mismo nombre. Si la aplicación no se va a reinstalar, un administrador puede eliminar allí sus reglas.",
+        it: "DSM mantiene le regole di {package} in Pannello di controllo > Privilegi applicazione dopo la disinstallazione e le applica di nuovo a una successiva installazione con lo stesso nome. Se l’applicazione non verrà reinstallata, un amministratore può rimuoverne le regole da lì.",
+    },
+    "uninstall.appPrivilege.auto": {
+        en: "Uninstall removes the rules of {package} in Control Panel > Application Privileges automatically, so a later install under the same name does not apply them again. Only if this cleanup failed, as the system log entry synopkgland-executor reports, an administrator can remove the rules there.",
+        "zh-TW": "解除安裝會自動移除 {package} 在「控制台」>「應用程式權限」中的規則，之後以相同名稱安裝時不會再次套用。只有在自動清除失敗時（系統日誌 synopkgland-executor 會記錄），管理員才需要在該處移除這些規則。",
+        "zh-CN": "卸载会自动删除 {package} 在“控制面板”>“应用程序权限”中的规则，之后以相同名称安装时不会再次应用。只有在自动清理失败时（系统日志 synopkgland-executor 会记录），管理员才需要在该处删除这些规则。",
+        ja: "アンインストール時に [コントロール パネル] > [アプリケーション権限] にある {package} のルールを自動的に削除するため、同じ名前で再インストールしても再び適用されません。この削除に失敗した場合 (システム ログの synopkgland-executor に記録されます) のみ、管理者がそこでルールを削除してください。",
+        ko: "제거 시 제어판 > 응용 프로그램 권한에 있는 {package}의 규칙을 자동으로 삭제하므로, 같은 이름으로 다시 설치해도 다시 적용되지 않습니다. 이 정리가 실패한 경우에만(시스템 로그 synopkgland-executor에 기록됨) 관리자가 그곳에서 규칙을 삭제하십시오.",
+        de: "Die Deinstallation entfernt die Regeln von {package} unter Systemsteuerung > Anwendungsberechtigungen automatisch, sodass eine spätere Installation unter demselben Namen sie nicht erneut anwendet. Nur wenn diese Bereinigung fehlschlägt, was der Systemprotokolleintrag synopkgland-executor meldet, muss ein Administrator die Regeln dort entfernen.",
+        fr: "La désinstallation supprime automatiquement les règles de {package} dans Panneau de configuration > Privilèges d’application, si bien qu’une installation ultérieure sous le même nom ne les applique pas de nouveau. Seulement si ce nettoyage échoue, ce que signale l’entrée synopkgland-executor du journal système, un administrateur doit y supprimer les règles.",
+        es: "La desinstalación elimina automáticamente las reglas de {package} en Panel de control > Privilegios de aplicaciones, de modo que una instalación posterior con el mismo nombre no las aplica de nuevo. Solo si esta limpieza falla, como indica la entrada synopkgland-executor del registro del sistema, un administrador debe eliminar allí las reglas.",
+        it: "La disinstallazione rimuove automaticamente le regole di {package} in Pannello di controllo > Privilegi applicazione, così una successiva installazione con lo stesso nome non le applica di nuovo. Solo se questa pulizia non riesce, come segnala la voce synopkgland-executor del registro di sistema, un amministratore deve rimuovere le regole da lì.",
+    },
+    "uninstall.portal.auto": {
+        en: "After DSM removes the Login Portal alias of {package}, uninstall reloads the web server automatically, so the alias stops at once. Only if this reload failed, as the system log entry synopkgland-executor reports, an administrator can save an application alias in Control Panel > Login Portal > Applications, which reloads the web server, or restart the NAS.",
+        "zh-TW": "DSM 移除 {package} 的登入入口別名後，解除安裝會自動重新載入網頁伺服器，讓該別名立即失效。只有在重新載入失敗時（系統日誌 synopkgland-executor 會記錄），管理員才需要在「控制台」>「登入入口」>「應用程式」儲存任一應用程式別名（會重新載入網頁伺服器），或重新啟動 NAS。",
+        "zh-CN": "DSM 删除 {package} 的登录门户别名后，卸载会自动重新加载网页服务器，使该别名立即失效。只有在重新加载失败时（系统日志 synopkgland-executor 会记录），管理员才需要在“控制面板”>“登录门户”>“应用程序”保存任一应用程序别名（会重新加载网页服务器），或重新启动 NAS。",
+        ja: "DSM が {package} のログイン ポータルのエイリアスを削除した後、アンインストール時に Web サーバーを自動的に再読み込みするため、エイリアスはすぐに無効になります。再読み込みに失敗した場合 (システム ログの synopkgland-executor に記録されます) のみ、管理者が [コントロール パネル] > [ログイン ポータル] > [アプリケーション] でいずれかのアプリケーションのエイリアスを保存する (Web サーバーが再読み込みされます) か、NAS を再起動してください。",
+        ko: "DSM이 {package}의 로그인 포털 별칭을 삭제한 후 제거 과정에서 웹 서버를 자동으로 다시 로드하므로 별칭이 즉시 중지됩니다. 다시 로드가 실패한 경우에만(시스템 로그 synopkgland-executor에 기록됨) 관리자가 제어판 > 로그인 포털 > 응용 프로그램에서 응용 프로그램 별칭을 저장하거나(웹 서버가 다시 로드됨) NAS를 다시 시작하십시오.",
+        de: "Nachdem DSM den Anmeldeportal-Alias von {package} entfernt hat, lädt die Deinstallation den Webserver automatisch neu, sodass der Alias sofort endet. Nur wenn dieses Neuladen fehlschlägt, was der Systemprotokolleintrag synopkgland-executor meldet, muss ein Administrator unter Systemsteuerung > Anmeldeportal > Anwendungen einen Anwendungsalias speichern, wodurch der Webserver neu geladen wird, oder das NAS neu starten.",
+        fr: "Après que DSM a supprimé l’alias du Portail de connexion de {package}, la désinstallation recharge automatiquement le serveur web, si bien que l’alias cesse immédiatement. Seulement si ce rechargement échoue, ce que signale l’entrée synopkgland-executor du journal système, un administrateur doit enregistrer un alias d’application dans Panneau de configuration > Portail de connexion > Applications, ce qui recharge le serveur web, ou redémarrer le NAS.",
+        es: "Después de que DSM elimine el alias del Portal de inicio de sesión de {package}, la desinstalación recarga automáticamente el servidor web, de modo que el alias deja de funcionar al instante. Solo si esta recarga falla, como indica la entrada synopkgland-executor del registro del sistema, un administrador debe guardar un alias de aplicación en Panel de control > Portal de inicio de sesión > Aplicaciones, lo que recarga el servidor web, o reiniciar el NAS.",
+        it: "Dopo che DSM ha rimosso l’alias del Portale di accesso di {package}, la disinstallazione ricarica automaticamente il server web, così l’alias smette subito di funzionare. Solo se questo ricaricamento non riesce, come segnala la voce synopkgland-executor del registro di sistema, un amministratore deve salvare un alias di applicazione in Pannello di controllo > Portale di accesso > Applicazioni, che ricarica il server web, oppure riavviare il NAS.",
+    },
     "uninstall.keep.native": {
         en: "Never deleted: Shared Folders, the package account, and other apps' data.",
         "zh-TW": "不會被刪除：共用資料夾（Shared Folder）、套件帳號，以及其他 App 的資料。",

package/dist/capability-overlays.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How each native-go capability is laid over the base template: the template
+ * directories copied on top, files borrowed from another overlay, and the
+ * base files the overlay replaces. init and add both read this table.
+ */
+export interface CapabilityOverlay {
+    overlays: string[];
+    borrowed: string[];
+    removed: string[];
+}
+export declare const CAPABILITY_OVERLAYS: Record<string, CapabilityOverlay>;
+/** The overlays of these capabilities, in table order, each once; a capability without one adds nothing. */
+export declare function capabilityOverlays(names: readonly string[]): CapabilityOverlay;
+/** A borrowed path names its overlay first; this is where it lands in a project. */
+export declare const borrowedTarget: (path: string) => string;

package/dist/capability-overlays.js

@@ -0,0 +1,18 @@
+const EXECUTOR_SHELL = ['backend/internal/app/executor.go', 'backend/internal/app/executor_test.go'];
+export const CAPABILITY_OVERLAYS = {
+    'root-ops': { overlays: ['native-go-root-ops'], borrowed: [], removed: ['backend/internal/app/root_none.go'] },
+    jobs: { overlays: ['native-go-jobs'], borrowed: [], removed: ['backend/internal/app/background_none.go'] },
+    delegate: {
+        overlays: ['native-go-jobs', 'native-go-delegate'],
+        borrowed: EXECUTOR_SHELL.map(file => `native-go-root-ops/${file}`),
+        removed: ['backend/internal/app/background_none.go', 'backend/internal/app/root_none.go', 'backend/internal/app/delegate_none.go'],
+    },
+};
+/** The overlays of these capabilities, in table order, each once; a capability without one adds nothing. */
+export function capabilityOverlays(names) {
+    const chosen = Object.entries(CAPABILITY_OVERLAYS).filter(([name]) => names.includes(name)).map(([, overlay]) => overlay);
+    const unique = (pick) => [...new Set(chosen.flatMap(pick))];
+    return { overlays: unique(o => o.overlays), borrowed: unique(o => o.borrowed), removed: unique(o => o.removed) };
+}
+/** A borrowed path names its overlay first; this is where it lands in a project. */
+export const borrowedTarget = (path) => path.split('/').slice(1).join('/');

package/dist/cli-version.d.ts

@@ -0,0 +1,2 @@
+/** This CLI's own release, read from its package.json. */
+export declare const CLI_VERSION: string;

package/dist/cli-version.js

@@ -0,0 +1,3 @@
+import { readFileSync } from "node:fs";
+/** This CLI's own release, read from its package.json. */
+export const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;

package/dist/cli.js

@@ -118,6 +118,7 @@ async function standaloneBuild(root, arches, options) {
     const result = isNativeLayout(root)
         ? await buildNativeLayout({ root, arches, outDir, minDsm: options.minDsm, jobs: options.jobs })
         : await buildStandalone({ root, arches: arches, outDir, minDsm: options.minDsm, jobs: options.jobs });
+    result.warnings?.forEach((warning) => console.error(warning));
     return result.outputs.map((output) => {
         if (!options.output)
             return output;
@@ -306,8 +307,9 @@ export async function runCli(argv) {
                 },
         });
         stdout(`已建立 ${options.template} 專案於 ${targetDir}`);
+        // --install-links packs a local SDK like the released package; a symlink would load the checkout's own node_modules.
         if (options.template === "native-go")
-            stdout(`下一步：\n  cd ${dir}\n  (cd backend && go test ./...)\n${existsSync(join(targetDir, "frontend", "package.json")) ? "  (cd frontend && npm ci)\n" : ""}  synopkgland build\n說明見 README.md。`);
+            stdout(`下一步：\n  cd ${dir}\n  (cd backend && go test ./...)\n${existsSync(join(targetDir, "frontend", "package.json")) ? `  (cd frontend && npm install${process.env.SYNOPKGLAND_SDK_DIR ? " --install-links" : ""})\n` : ""}  synopkgland build\n說明見 README.md。`);
     });
     program
         .command("add <caps...>")
@@ -458,7 +460,7 @@ export async function runCli(argv) {
         .option("--json", "輸出單一 JSON 物件")
         .option("-o, --output <path>", "輸出 SPK，搭配單一 --arch")
         .option("--out-dir <dir>", "輸出目錄，原生專案預設 dist/")
-        .option("--arch <families>", `架構，可用逗號分隔：${NATIVE_ARCH_FAMILIES.join(",")}（armv7 用於 native-go 與 binary，不用於 Container Manager App）；native layout 另支援 armv8`)
+        .option("--arch <families>", `架構，可用逗號分隔或重複指定：${NATIVE_ARCH_FAMILIES.join(",")}（armv7 用於 native-go 與 binary，不用於 Container Manager App）；native layout 另支援 armv8`, (value, previous) => [...(previous ?? []), value])
         .option("--min-dsm <version>", "最低 DSM 版本，省略時使用 manifest 值")
         .option("--jobs <n>", "同時建置的架構數，預設 1（依序）", Number)
         .option("--verify-reproducible [when]", "從乾淨狀態再建置一次並比對；when：changed（預設，依賴指紋未變時略過）或 always")
@@ -474,12 +476,12 @@ export async function runCli(argv) {
                 options.arch === undefined
                     ? undefined
                     : standalone && isNativeLayout(standalone)
-                        ? String(options.arch).split(",").map((arch) => {
+                        ? options.arch.join(",").split(",").map((arch) => {
                             if (!Object.hasOwn(LAYOUT_ARCHES, arch))
                                 throw new Error(`Native layout arch must be one of ${Object.keys(LAYOUT_ARCHES).join(", ")}`);
                             return arch;
                         })
-                        : parseArchList(String(options.arch));
+                        : parseArchList(options.arch.join(","));
         }
         catch (error) {
             throw failure("CLI_ARCH_INVALID", error instanceof Error ? error.message : String(error));

package/dist/contract/validate.js

@@ -4,13 +4,11 @@ import { contractSpan, makeError } from "../errors.js";
 import { collectInstallParameters, getValuePosition, stringViolations, } from "./load.js";
 import { validateContractSchema } from "./schema-validate.js";
 import { DSM_GROUP_NAME, isWebAccessMode, isWebLaunchMode, readWebIntegration } from "./web-launch.js";
-import { contractPortalSupported, readPortalDeclaration } from "../portal/alias.js";
 import { validateContractIcon } from "./icon.js";
 import { validateContractI18n } from "./i18n.js";
 import { loadCompose } from "../compose/analyze.js";
 import { collectPosixAllSharesParameters, isPosixAllSharesType, validatePosixAllSharesSources, } from "./posix-all-shares.js";
 import { getErrorCode } from "../error-registry.js";
-import { isDsmAtLeast, PORTAL_MIN_DSM, portalMinDsmMessage } from "../build-spk/dsm-version.js";
 import { FORMAL_PACKAGE_IDENTITY_MAX_LENGTH, PACKAGE_IDENTITY_MAX_LENGTH, } from "../deploy/identity-shared.js";
 /** DSM 7.4 Package Center rejects a longer package identity outright. */
 const DSM_PACKAGE_IDENTITY_MAX = 32;
@@ -133,26 +131,11 @@ function validateWebPortal(parsed, contractFile) {
         return [];
     }
     const pos = getValuePosition(doc, ["integration", "web", "portal"]) ?? { line: 1, column: 1 };
-    const at = contractSpan(contractFile, pos.line, pos.column, "integration.web.portal");
-    if (!contractPortalSupported(contract)) {
-        return [
-            makeError("CONTRACT_PORTAL_UNSUPPORTED", at, "Application Portal 只支援以 DSM 視窗開啟、經 DSM 登入閘道的網頁 App。", "請使用 adminport、launch: dsm-window 與非 public 的 access，或移除 integration.web.portal。public App 已有同名的 Web Station 網址。"),
-        ];
-    }
-    if (!readPortalDeclaration(portal, String(contract.package ?? ""))) {
-        return [
-            makeError("CONTRACT_PORTAL_INVALID", at, "integration.web.portal 必須是 {} 或 { alias }，alias 為 1–64 個小寫英數字或 -，且不是 DSM 保留路徑。", "請省略 alias 以使用套件名稱，或改成例如 alias: my-app。"),
-        ];
-    }
-    const osMinVer = contract.os_min_ver;
-    if (typeof osMinVer === "string" && FULL_OS_MIN_VER.test(osMinVer) && !isDsmAtLeast(osMinVer, PORTAL_MIN_DSM)) {
-        return [
-            makeError("CONTRACT_PORTAL_MIN_DSM", at, portalMinDsmMessage(osMinVer, "integration.web.portal"), `請把 os_min_ver 改成 "${PORTAL_MIN_DSM}" 或更新，或移除 integration.web.portal。`),
-        ];
-    }
-    return [];
+    // A Compose App has no root executor, and only its purge can stop nginx serving the alias after uninstall.
+    return [
+        makeError("CONTRACT_PORTAL_REQUIRES_EXECUTOR", contractSpan(contractFile, pos.line, pos.column, "integration.web.portal"), "Compose App 沒有 executor，不能宣告 Application Portal：解除安裝後 DSM 不會 reload nginx，別名要 root 才能清除。", "請移除 integration.web.portal；需要登入入口別名時，由管理員在 DSM 手動設定反向代理。"),
+    ];
 }
-const FULL_OS_MIN_VER = /^7\.\d+(\.\d+)?-\d+$/;
 function validateDeveloperString(value, contractFile, path, pos) {
     const errors = [];
     const violations = stringViolations(value);

package/dist/error-registry.js

@@ -59,15 +59,10 @@ export const ERROR_REGISTRY = {
         "description": "Headless App 不需要宣告 Web Launch Mode。",
         "suggestion": "請省略 integration.web.launch，或補上對應 Compose published port 的 adminport。"
     },
-    "CONTRACT_PORTAL_INVALID": {
-        "code": "CONTRACT_PORTAL_INVALID",
-        "description": "integration.web.portal 的格式或 alias 不正確。",
-        "suggestion": "請使用 {} 或 { alias: my-app }；alias 為 1–64 個小寫英數字或 -，且不是 DSM 保留路徑。"
-    },
-    "CONTRACT_PORTAL_UNSUPPORTED": {
-        "code": "CONTRACT_PORTAL_UNSUPPORTED",
-        "description": "這個 App 的網頁入口無法加入 DSM Application Portal。",
-        "suggestion": "Application Portal 需要 adminport、launch: dsm-window 與非 public 的 access；否則請移除 integration.web.portal。"
+    "CONTRACT_PORTAL_REQUIRES_EXECUTOR": {
+        "code": "CONTRACT_PORTAL_REQUIRES_EXECUTOR",
+        "description": "Compose App 宣告了 integration.web.portal；Compose App 沒有 executor，登入入口別名在解除安裝後要 root 才能讓 nginx 停止提供。",
+        "suggestion": "請移除 integration.web.portal；需要登入入口別名時，由管理員在 DSM 手動設定反向代理。"
     },
     "CONTRACT_ACCESS_INVALID": {
         "code": "CONTRACT_ACCESS_INVALID",
@@ -102,7 +97,7 @@ export const ERROR_REGISTRY = {
     "GATEWAY_BUILD_FAILED": {
         "code": "GATEWAY_BUILD_FAILED",
         "description": "DSM 驗證閘道建置失敗或產出不是對應架構的靜態 ELF。",
-        "suggestion": "請查看 go build 輸出；閘道固定以 go1.26.9 建置，離線時請安裝 go1.26.9 或讓 GOPROXY 可提供 golang.org/toolchain，並確認 templates/_gateway 未被修改。"
+        "suggestion": "請查看 go build 輸出；閘道固定以 go1.26.9 建置，離線時請安裝 go1.26.9 或讓 GOPROXY 可提供 golang.org/toolchain，並確認 CLI 套件的 assets/go/gateway 未被修改。"
     },
     "CONTRACT_INVALID_STRING": {
         "code": "CONTRACT_INVALID_STRING",
@@ -587,13 +582,18 @@ export const ERROR_REGISTRY = {
     "STANDALONE_GO_BUILD_FAILED": {
         "code": "STANDALONE_GO_BUILD_FAILED",
         "description": "go build 失敗。",
-        "suggestion": "請在 backend 目錄執行 go build ./... 並修正錯誤。"
+        "suggestion": "請在 backend 目錄執行 go build ./... 並修正錯誤。取不到 github.com/synopackageland/syno-pkg-land-sdk 時，設定 GOPRIVATE=github.com/synopackageland/* 並讓 git 能以憑證讀 github.com。"
     },
     "STANDALONE_PORTAL_INVALID": {
         "code": "STANDALONE_PORTAL_INVALID",
         "description": "dsm-package.yaml 的 portal 格式或 alias 不正確。",
         "suggestion": "請使用 portal: {} 或 portal: { alias: my-app }；alias 為 1–64 個小寫英數字或 -，且不是 DSM 保留路徑。"
     },
+    "STANDALONE_PORTAL_REQUIRES_EXECUTOR": {
+        "code": "STANDALONE_PORTAL_REQUIRES_EXECUTOR",
+        "description": "沒有 executor（capabilities.rootOps 或 delegate）的 App 宣告了 portal。",
+        "suggestion": "登入入口別名在解除安裝後要 root 才能讓 nginx 停止提供，而無升權 App 任何階段都不使用 root。請加 capabilities.rootOps 或 delegate（executor 層級），或移除 portal，改由管理員在 DSM 手動設定反向代理。"
+    },
     "STANDALONE_I18N_INVALID": {
         "code": "STANDALONE_I18N_INVALID",
         "description": "dsm-package.yaml 的 i18n 設定不合法。",
@@ -649,8 +649,7 @@ for (const [code, description, suggestion] of [
     ERROR_REGISTRY[code] = { code, description, suggestion };
 ERROR_REGISTRY["ADD_LAYOUT_UNSUPPORTED"] = { "code": "ADD_LAYOUT_UNSUPPORTED", "description": "SDK overlay 需要標準 backend 目錄。", "suggestion": "使用 backend.dir: backend，或手動合併 SDK overlay。" };
 ERROR_REGISTRY["MIN_DSM_CONTAINER_FLOOR"] = { "code": "MIN_DSM_CONTAINER_FLOOR", "description": "Compose 最低 DSM 版本過低。", "suggestion": "Compose 需要 DSM 7.2.1-69057 或以上。" };
-for (const code of ["STANDALONE_PORTAL_MIN_DSM", "CONTRACT_PORTAL_MIN_DSM"])
-    ERROR_REGISTRY[code] = { code, "description": "宣告 portal 的套件 os_min_ver 低於 DSM 7.3.2-86009。", "suggestion": "DSM 7.1.1 以 320 拒裝帶 portal 的未簽章套件、7.2 未驗證；把 os_min_ver 提高到 7.3.2-86009 以上，或移除 portal。" };
+ERROR_REGISTRY.STANDALONE_PORTAL_MIN_DSM = { "code": "STANDALONE_PORTAL_MIN_DSM", "description": "宣告 portal 的套件 os_min_ver 低於 DSM 7.3.2-86009。", "suggestion": "DSM 7.1.1 以 320 拒裝帶 portal 的未簽章套件、7.2 未驗證；把 os_min_ver 提高到 7.3.2-86009 以上，或移除 portal。" };
 ERROR_REGISTRY["MIN_DSM_INVALID"] = { "code": "MIN_DSM_INVALID", "description": "最低 DSM 版本格式不合法。", "suggestion": "指定 7.x release 或完整 7.x-build。" };
 ERROR_REGISTRY["NOTICE_UNSAFE"] = { "code": "NOTICE_UNSAFE", "description": "授權檔案不符合一般檔案限制。", "suggestion": "移除 symlink、特殊檔與超大授權檔案。" };
 ERROR_REGISTRY["NOTICE_MISSING"] = { "code": "NOTICE_MISSING", "description": "缺少第三方授權資訊。", "suggestion": "重新安裝模板依賴並產生 third-party notices。" };
@@ -695,7 +694,15 @@ export function getErrorCode(code) {
     return ERROR_REGISTRY[code];
 }
 for (const [code, description, suggestion] of [
-    ["EXECUTOR_BUILD_FAILED", "executor 或 lifecycle helper 編譯失敗，或 CLI 套件缺少 executor 原始碼。", "確認已安裝 Go 1.21 以上且可取得 go1.26.9（離線時請先備妥），查看訊息中的編譯器輸出；原始碼缺少時重新安裝 CLI。"],
+    ["EXECUTOR_BUILD_FAILED", "從 App 相依的 SDK 版本編譯 executor 或 lifecycle helper 失敗。", "確認已安裝 Go 1.21 以上且可取得 go1.26.9（離線時請先備妥），查看訊息中的編譯器輸出。"],
+    ["EXECUTOR_DIGEST_MISMATCH", "由 SDK 版本建出的 executor 與 CLI 內建的 sha256 表不符，或表中沒有這個 SDK 版本。", "確認 backend/go.mod 的 github.com/synopackageland/syno-pkg-land-sdk 是正式版本且 Go 為 go1.26.9；表中沒有該版本時升級 CLI。"],
+    ["EXECUTOR_DIGEST_UNVERIFIED", "SYNOPKGLAND_SDK_DIR 指向本機 SDK，executor 未對照 sha256 表（警告）。", "只用於開發；要發佈的 SPK 請取消 SYNOPKGLAND_SDK_DIR 後重新 build。"],
+    ["SDK_REQUIRED", "rootOps 或 delegate 需要 SDK，但 backend/go.mod 沒有 require github.com/synopackageland/syno-pkg-land-sdk。", "在 backend/go.mod 加入 require github.com/synopackageland/syno-pkg-land-sdk 與 CLI 同一 minor 的版本，或改用 init 產生的 Go 後端。"],
+    ["SDK_VERSION_MISMATCH", "frontend/package.json 的 @synopackageland/sdk 與 backend/go.mod 要求的 SDK 版本不同。", "把兩邊改成同一個版本；file: 相依時，比對的是該目錄 package.json 的 version。"],
+    ["SDK_UNSUPPORTED", "backend/go.mod 要求的 SDK 不是這個 CLI 的 minor 版本線。", "改用與 SDK 同一 minor 的 CLI，或把 SDK 升到 CLI 支援的版本線（訊息列出）。"],
+    ["SDK_DIR_NOT_READY", "SYNOPKGLAND_SDK_DIR 指向的 SDK checkout 根目錄缺少 go.mod，或 Vue 專案需要的 ts 套件尚未建置（沒有 ts/dist）。", "指向 syno-pkg-land-sdk checkout；Vue 專案先在 $SYNOPKGLAND_SDK_DIR/ts 執行 npm ci && npm run build（npm 安裝 file: 套件時不會替它 build）。"],
+    ["SDK_DOWNLOAD_FAILED", "go mod download 取不到 backend/go.mod 要求的 SDK 版本。", "SDK repo 目前是 private，不能經 proxy.golang.org 取得：設定 GOPRIVATE=github.com/synopackageland/*（例如 go env -w），並讓 git 能以憑證讀 github.com（git ls-remote 可驗證）；再確認版本存在。離線時先在同一台機器 go mod download 一次。"],
+    ["TEMPLATES_MISSING", "找不到 @synopackageland/templates。", "重新安裝 @synopackageland/cli，或把 SYNOPKGLAND_TEMPLATES_DIR 指向 templates checkout。"],
     ["EXECUTOR_PIN_REQUIRED", "宣告 rootOps 或 delegate 的套件建置時沒有 executor 產物。", "使用 synopkgland build，讓 CLI 編譯並 pin executor；不要直接呼叫低階 SPK API。"],
     ["EXECUTOR_POLICY", "capabilities.delegate 的 operations 或 scope 不合法，無法產生 executor policy。", "改用 init／add 產生的 delegate 宣告，或依 manifest 參考修正 scope 與 operations。"],
     ["EXECUTOR_PACKAGE", "pin 進 root task 的套件名稱不合法。", "package 必須以英文字母開頭，只含英數字（2–64 字）。"],
@@ -706,7 +713,7 @@ for (const [code, description, suggestion] of [
     ERROR_REGISTRY[code] = { code, description, suggestion };
 ERROR_REGISTRY["STANDALONE_ENTRY_INVALID"] = { "code": "STANDALONE_ENTRY_INVALID", "description": "entry 設定不合法。", "suggestion": "entry 填 admin-only 或 app-privilege；app-privilege 需要至少一個 authenticated route。" };
 ERROR_REGISTRY["STANDALONE_ENTRY_WIDENED"] = { "code": "STANDALONE_ENTRY_WIDENED", "description": "entry: admin-only 與放寬權限的 route 設定衝突。", "suggestion": "把 permissions.json 中 authenticated 或 public 的 route 改為 administrators；要開放給一般使用者請改用 entry: app-privilege 或省略 entry。" };
-ERROR_REGISTRY["STANDALONE_ENTRY_UNSUPPORTED"] = { "code": "STANDALONE_ENTRY_UNSUPPORTED", "description": "backend 無法強制 entry 模式。", "suggestion": "使用 Go backend，複製 SDK 的 internal/dsm entry gate 並在 cmd/app/main.go 呼叫 dsm.NewEntryGate。" };
+ERROR_REGISTRY["STANDALONE_ENTRY_UNSUPPORTED"] = { "code": "STANDALONE_ENTRY_UNSUPPORTED", "description": "backend 無法強制 entry 模式。", "suggestion": "使用 Go backend：backend/go.mod require github.com/synopackageland/syno-pkg-land-sdk，並在 backend.main 的 main.go（init 預設為 cmd/app/main.go）以 dsm.NewEntryGate 包住 authenticator。" };
 ERROR_REGISTRY["DSM_TLS_UNTRUSTED"] = { "code": "DSM_TLS_UNTRUSTED", "description": "DSM 的 TLS 憑證不受這台電腦信任（自簽、過期或名稱不符）。", "suggestion": "把 NAS 憑證或其 CA 匯出成 PEM，用 NODE_EXTRA_CA_CERTS=<該檔> 執行；或讓 DSM 使用與 host profile 名稱相符的受信任憑證。不要關閉憑證驗證。" };
 ERROR_REGISTRY["STANDALONE_ICON_INVALID"] = { "code": "STANDALONE_ICON_INVALID", "description": "dsm-package.yaml 的 icon 不是可用的套件圖示。", "suggestion": "icon 填專案內的正方形 PNG（至少 256×256），或含 icon_256.png 的 icon_<size>.png 目錄；省略則使用 SDK 預設圖示。" };
 ERROR_REGISTRY["CONTRACT_ICON_INVALID"] = { "code": "CONTRACT_ICON_INVALID", "description": "synology-app.yaml 的 icon 不是可用的套件圖示。", "suggestion": "icon 填專案內的正方形 PNG（至少 256×256），或含 icon_256.png 的 icon_<size>.png 目錄；省略則使用 SDK 預設圖示。" };

package/dist/host/dsm-client.js

@@ -92,6 +92,43 @@ function createDsmNasHost(credentials, profileName) {
         if (!cookieHeader)
             throw new Error("DSM login returned no session cookie");
     };
+    /**
+     * One read-only call of the App's own CGI as the administrator. identity:
+     * standalone wraps business methods in an App session: trade the DSM cookie
+     * for one (same Origin), read once, then end that session. Undefined when
+     * the App refuses; `error` when no App session could be opened.
+     */
+    const readApp = async (packageIdentity, method) => {
+        await ensureLogin();
+        const appCall = async (name, cookie) => {
+            const response = await dsmFetch(`${dsmOrigin}/webman/3rdparty/${encodeURIComponent(packageIdentity)}/cgi/api.cgi`, {
+                method: "POST", headers: { cookie, origin: dsmOrigin, "content-type": "application/json" },
+                body: JSON.stringify({ method: name, params: name === "identity.session" ? { bootstrap: true } : {} }),
+            });
+            const body = await response.json();
+            return { body, setCookie: setCookiePairs(response.headers) };
+        };
+        const direct = await appCall(method, cookieHeader ?? "");
+        if (direct.body.success)
+            return { data: direct.body.data };
+        if (direct.body.error?.code !== "session_required")
+            return undefined;
+        const session = await appCall("identity.session", cookieHeader ?? "");
+        if (!session.body.success) {
+            const code = session.body.error?.code;
+            return { error: code === "https_required"
+                    ? "identity: standalone status needs an https:// DSM host profile to open an App session."
+                    : `identity: standalone App session bootstrap failed (${code ?? "error"}).` };
+        }
+        const appCookie = [cookieHeader ?? "", ...session.setCookie].filter(Boolean).join("; ");
+        try {
+            const status = await appCall(method, appCookie);
+            return status.body.success ? { data: status.body.data } : undefined;
+        }
+        finally {
+            await appCall("identity.logout", appCookie).catch(() => undefined);
+        }
+    };
     return {
         dsmOrigin,
         async installFromLocalSpk(input) {
@@ -108,39 +145,23 @@ function createDsmNasHost(credentials, profileName) {
         },
         async getExecutorStatus(packageIdentity) {
             try {
-                await ensureLogin();
-                const appCall = async (method, cookie) => {
-                    const response = await dsmFetch(`${dsmOrigin}/webman/3rdparty/${encodeURIComponent(packageIdentity)}/cgi/api.cgi`, {
-                        method: "POST", headers: { cookie, origin: dsmOrigin, "content-type": "application/json" },
-                        body: JSON.stringify({ method, params: method === "identity.session" ? { bootstrap: true } : {} }),
-                    });
-                    const body = await response.json();
-                    return { body, setCookie: setCookiePairs(response.headers) };
-                };
                 // A paused executor answers with why and what to do next.
                 const explain = (status) => status.state === "paused" ? { ...status, error: `Executor paused (${status.reason}). ${status.next}` } : status;
-                const direct = await appCall("executor.status", cookieHeader ?? "");
-                if (direct.body.success)
-                    return explain(direct.body.data);
-                // identity: standalone wraps business methods in an App session; trade the
-                // administrator's DSM cookie for one, read once, then end that session.
-                if (direct.body.error?.code !== "session_required")
+                const read = await readApp(packageIdentity, "executor.status");
+                if (!read)
                     return undefined;
-                const session = await appCall("identity.session", cookieHeader ?? "");
-                if (!session.body.success) {
-                    const code = session.body.error?.code;
-                    return { ready: false, executor_digest: "", policy_digest: "", error: code === "https_required"
-                            ? "identity: standalone status needs an https:// DSM host profile to open an App session."
-                            : `identity: standalone App session bootstrap failed (${code ?? "error"}).` };
-                }
-                const appCookie = [cookieHeader ?? "", ...session.setCookie].filter(Boolean).join("; ");
-                try {
-                    const status = await appCall("executor.status", appCookie);
-                    return status.body.success ? explain(status.body.data) : undefined;
-                }
-                finally {
-                    await appCall("identity.logout", appCookie).catch(() => undefined);
-                }
+                if ("error" in read)
+                    return { ready: false, executor_digest: "", policy_digest: "", error: read.error };
+                return explain(read.data);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async getPortalStatus(packageIdentity) {
+            try {
+                const read = await readApp(packageIdentity, "portal.status");
+                return read && "data" in read ? read.data : undefined;
             }
             catch {
                 return undefined;

package/dist/host/types.d.ts

@@ -35,6 +35,11 @@ export interface NasHost {
         policy_digest: string;
         error?: string;
     } | undefined>;
+    /** The App's `portal.status`: whether an administrator set its Application Portal alias. */
+    getPortalStatus?(packageIdentity: string): Promise<{
+        state: string;
+        alias?: string;
+    } | undefined>;
     getArchFamily?(): Promise<NativeArchFamily | undefined>;
     /** List the current logical Shared Folder names using an administrator session. */
     listShareNames?(): Promise<string[]>;

package/dist/info.js

@@ -8,6 +8,7 @@ import { inspectSpk } from "./standalone/inspect-spk.js";
 import { isNativeLayout, loadNativeLayout } from "./standalone/native-layout.js";
 import { executorPolicy, executorPolicyText, sha256 } from "./runtime/executor-policy.js";
 import { executorTasks } from "./runtime/executor-tasks.js";
+import { requiredSdk } from "./runtime/sdk-source.js";
 import { uninstallCleanup } from "./runtime/uninstall-cleanup.js";
 export async function projectInfo(options) {
     const identity = resolveDeployIdentity(options.project, { dev: options.dev });
@@ -68,7 +69,7 @@ export function classifyRootTasks(expected, inventory) {
 async function liveRootCapability(m, host) {
     try {
         const policyDigest = sha256(executorPolicyText(executorPolicy(m)));
-        const classified = classifyRootTasks(executorTasks({ package: m.package, policyDigest }), await host.getRootTaskInventory?.(m.package));
+        const classified = classifyRootTasks(executorTasks({ package: m.package, policyDigest }, requiredSdk(m.backend.kind === "go" ? m.backend.dir : m.root).executorDir), await host.getRootTaskInventory?.(m.package));
         if (classified.state !== "ready")
             return classified;
         const observed = await host.getExecutorStatus?.(m.package);
@@ -160,13 +161,26 @@ export async function standaloneInfo(options) {
                 reason: "Installed package supports this capability without administrator approval.",
             });
     }
+    if (m.portal)
+        capabilities.push(installed ? await portalCapability(m.package, m.portal.alias, options.host) : {
+            name: "portal", state: "blocked", reason: "Package is not installed; deploy first.",
+        });
     return {
         ...state,
         capabilities,
         ...(executor ? { executor } : {}),
-        uninstallCleanup: uninstallCleanup(m.package, Boolean(m.capabilities.rootOps || m.capabilities.delegate)),
+        uninstallCleanup: uninstallCleanup(m.package, { executor: Boolean(m.capabilities.rootOps || m.capabilities.delegate), portal: Boolean(m.portal) }),
     };
 }
+/** What the installed App's portal.status says; DSM owns the alias, an administrator sets it. */
+async function portalCapability(pkg, defaultAlias, host) {
+    const status = await host.getPortalStatus?.(pkg);
+    if (status?.state === "active" && status.alias)
+        return { name: "portal", state: "ready", reason: `Users open the App at ${host.dsmOrigin.replace(/\/$/, "")}/${encodeURIComponent(status.alias)}/ after DSM sign-in.` };
+    if (status?.state === "inactive")
+        return { name: "portal", state: "needs-admin-approval", reason: `No alias is set; an administrator applies one (default ${defaultAlias}) in the App's Application Portal panel.` };
+    return { name: "portal", state: "blocked", reason: "The App's portal.status could not be read; open the App window to check the Application Portal." };
+}
 /** A native layout has no SDK capabilities; report package state only. */
 async function nativeLayoutInfo(root, host) {
     const loaded = loadNativeLayout(root);