@synopackageland/cli 0.9.0 → 0.9.1

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

@@ -161,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);

package/dist/init.js

@@ -119,7 +119,7 @@ export function initFromTemplate(template, targetDir, options = {}) {
     const shared = join(templatesRoot(), "_shared");
     const sharedFiles = ["LICENSES/TEMPLATE.txt", "AGENTS.md", "CLAUDE.md"];
     const files = [...templateFiles(source), ...sharedFiles, ...overlays.flatMap(root => templateFiles(root)),
-        ...(ui === "vue" ? ["frontend/third-party-notices.mjs"] : [])];
+        ...capability.borrowed.map(borrowedTarget), ...(ui === "vue" ? ["frontend/third-party-notices.mjs"] : [])];
     const collisions = files.map(targetName).filter((file) => existsSync(join(targetDir, file)));
     if (collisions.length > 0) {
         throw new Error(`[INIT_TARGET_NOT_EMPTY] ${targetDir} 已有 ${collisions.join(", ")}；init 不會覆蓋既有檔案。請改用空目錄。`);

package/dist/portal/alias.d.ts

@@ -1,4 +1,3 @@
-import type { AppContract } from "../types.js";
 /**
  * DSM Application Portal alias: `https://<nas>/<alias>/` opens the App after
  * DSM sign-in. DSM itself only refuses empty aliases (4100), synoman
@@ -12,6 +11,12 @@ export declare const PORTAL_ALIAS_MAX = 64;
  * of Synology Apps, as observed on DSM 7.4-90069. DSM stays the authority.
  */
 export declare const RESERVED_PORTAL_ALIASES: readonly string[];
+/**
+ * A portal needs the executor tier: DSM removes the alias files on uninstall
+ * but leaves nginx serving the alias, and only the root executor purge can
+ * reload it. A no-privilege App never runs anything as root.
+ */
+export declare const PORTAL_REQUIRES_EXECUTOR = "portal \u9700\u8981 executor \u5C64\u7D1A\uFF08capabilities.rootOps \u6216 delegate\uFF09\uFF1A\u89E3\u9664\u5B89\u88DD\u5F8C DSM \u4E0D\u6703 reload nginx\uFF0C\u767B\u5165\u5165\u53E3\u5225\u540D\u8981\u7531 root executor \u6E05\u9664\u3002\u6C92\u6709 executor \u7684 App \u8ACB\u79FB\u9664 portal\uFF0C\u6539\u7531\u7BA1\u7406\u54E1\u5728 DSM \u624B\u52D5\u8A2D\u5B9A\u53CD\u5411\u4EE3\u7406\u3002";
 export interface PortalDeclaration {
     alias: string;
 }
@@ -20,6 +25,3 @@ export declare function isPortalAlias(value: unknown): value is string;
 export declare function defaultPortalAlias(packageId: string): string;
 /** `{}` or `{alias}`; undefined for any other shape. */
 export declare function readPortalDeclaration(value: unknown, packageId: string): PortalDeclaration | undefined;
-/** A Compose App reaches the portal only as a DSM window behind the DSM-authenticated gateway. */
-export declare function contractPortalSupported(contract: AppContract): boolean;
-export declare function resolvedContractPortal(contract: AppContract): PortalDeclaration | undefined;

package/dist/portal/alias.js

@@ -1,5 +1,4 @@
 import { createHash } from "node:crypto";
-import { readWebIntegration, resolvedWebLaunch, usesAuthGateway } from "../contract/web-launch.js";
 /**
  * DSM Application Portal alias: `https://<nas>/<alias>/` opens the App after
  * DSM sign-in. DSM itself only refuses empty aliases (4100), synoman
@@ -16,6 +15,12 @@ export const RESERVED_PORTAL_ALIASES = [
     "dsfile", "indexdb", "mobile", "oauth", "scripts", "sharing", "ssdp", "synosdsjslib", "synohdpack", "webapi", "webman",
     "calendar", "chatplus", "contacts", "drive", "file", "photo", "sso", "synologymeet",
 ];
+/**
+ * A portal needs the executor tier: DSM removes the alias files on uninstall
+ * but leaves nginx serving the alias, and only the root executor purge can
+ * reload it. A no-privilege App never runs anything as root.
+ */
+export const PORTAL_REQUIRES_EXECUTOR = "portal 需要 executor 層級（capabilities.rootOps 或 delegate）：解除安裝後 DSM 不會 reload nginx，登入入口別名要由 root executor 清除。沒有 executor 的 App 請移除 portal，改由管理員在 DSM 手動設定反向代理。";
 export function isPortalAlias(value) {
     return typeof value === "string" && PORTAL_ALIAS_PATTERN.test(value) && !RESERVED_PORTAL_ALIASES.includes(value);
 }
@@ -36,13 +41,3 @@ export function readPortalDeclaration(value, packageId) {
         return { alias: defaultPortalAlias(packageId) };
     return isPortalAlias(alias) ? { alias } : undefined;
 }
-/** A Compose App reaches the portal only as a DSM window behind the DSM-authenticated gateway. */
-export function contractPortalSupported(contract) {
-    return resolvedWebLaunch(contract) === "dsm-window" && usesAuthGateway(contract);
-}
-export function resolvedContractPortal(contract) {
-    const portal = readWebIntegration(contract)?.portal;
-    if (portal === undefined || !contractPortalSupported(contract))
-        return undefined;
-    return readPortalDeclaration(portal, String(contract.package ?? ""));
-}

package/dist/portal/package.d.ts

@@ -1,6 +1,5 @@
 import type { Translate } from "../build-spk/wizard-i18n.js";
 import type { InstallWizardStep } from "../build-spk/install-wizard.js";
-import type { AppContract } from "../types.js";
 /** Package payload paths DSM's app-portal worker copies to /usr/syno/etc/www/app.d at start. */
 export declare const PORTAL_JSON_RELPATH = "etc/portal.json";
 export declare const PORTAL_MUSTACHE_RELPATH = "etc/portal.mustache";
@@ -16,8 +15,6 @@ export interface PortalPackage {
     /** Default alias; the wizard answer replaces it. */
     alias: string;
 }
-/** A Compose portal opens the App's `.url` entry of ui/config, keyed by the package id. */
-export declare function contractPortal(contract: AppContract): PortalPackage | undefined;
 export declare function portalResource(): Record<string, unknown>;
 /** Every field of DSM's own app.d files; the worker refuses a partial file (synopkg start 272). */
 export declare function renderPortalJson(portal: PortalPackage): string;

package/dist/portal/package.js

@@ -1,4 +1,4 @@
-import { PORTAL_ALIAS_MAX, PORTAL_ALIAS_PATTERN, RESERVED_PORTAL_ALIASES, resolvedContractPortal } from "./alias.js";
+import { PORTAL_ALIAS_MAX, PORTAL_ALIAS_PATTERN, RESERVED_PORTAL_ALIASES } from "./alias.js";
 /** Package payload paths DSM's app-portal worker copies to /usr/syno/etc/www/app.d at start. */
 export const PORTAL_JSON_RELPATH = "etc/portal.json";
 export const PORTAL_MUSTACHE_RELPATH = "etc/portal.mustache";
@@ -6,12 +6,6 @@ export const PORTAL_MUSTACHE_RELPATH = "etc/portal.mustache";
 export const PORTAL_INSTALL_KEY = "portal_alias";
 /** Package-owned install draft, never DSM's saved portal configuration. */
 export const PORTAL_DRAFT = "portal-install.json";
-/** A Compose portal opens the App's `.url` entry of ui/config, keyed by the package id. */
-export function contractPortal(contract) {
-    const portal = resolvedContractPortal(contract);
-    const packageId = String(contract.package);
-    return portal && { appId: packageId, application: String(contract.displayname ?? packageId), alias: portal.alias };
-}
 export function portalResource() {
     return { "web-config": { "app-portal": { "json-relpath": PORTAL_JSON_RELPATH, "mustache-relpath": PORTAL_MUSTACHE_RELPATH } } };
 }

package/dist/runtime/executor-digests.json

@@ -9,5 +9,16 @@
             "armv7": "b65a14f0fc77a1d3221c7dc6781eb66059aa200956b094d58a62bd1cad10f116"
         },
         "goToolchain": "go1.26.9"
+    },
+    "0.9.1": {
+        "x86_64": "5d75af3ce1de5b1d3ef5d89e062be1651a8e8b84edbca9903eb1a0b81d122fb5",
+        "aarch64": "b0e1f8174bf53eb435616ae0faf39ac929b515056f0b2fad5a6c264a1ff7f6e2",
+        "armv7": "17db613a4bdb181e0aa0f127822bfc13d7473fa846aadfbac3344b7c17700a84",
+        "lifecycle": {
+            "x86_64": "819459580135e016184ad80c258350d57194d6134e8aa4cf1caf5237085b1004",
+            "aarch64": "5abcfc21403e84a0af15d972bcb819ac6fedfd9aaf5898ddc8c4bb06130f9f59",
+            "armv7": "b65a14f0fc77a1d3221c7dc6781eb66059aa200956b094d58a62bd1cad10f116"
+        },
+        "goToolchain": "go1.26.9"
     }
 }

package/dist/runtime/uninstall-cleanup.d.ts

@@ -4,4 +4,10 @@ export interface UninstallCleanupItem {
     condition: string;
     action: string;
 }
-export declare function uninstallCleanup(pkg: string, executor: boolean): UninstallCleanupItem[];
+export interface UninstallCleanupOptions {
+    /** The App runs the root executor, which purges DSM's leftovers on uninstall. */
+    executor?: boolean;
+    /** The App declares a Login Portal alias; only the executor tier can. */
+    portal?: boolean;
+}
+export declare function uninstallCleanup(pkg: string, { executor, portal }?: UninstallCleanupOptions): UninstallCleanupItem[];

package/dist/runtime/uninstall-cleanup.js

@@ -1,7 +1,13 @@
-export function uninstallCleanup(pkg, executor) {
+const AUTOMATIC_FAILED = 'Only if automatic cleanup failed after uninstall; see the system log entry synopkgland-executor.';
+export function uninstallCleanup(pkg, { executor = false, portal = false } = {}) {
     const items = [
         { target: `@appdata/${pkg}, @appconf/${pkg}, @apphome/${pkg}`, condition: 'After uninstall, if retained data or empty DSM directories are no longer needed.', action: 'Back up retained data; an administrator may remove only these package-specific directories. The delete-data checkbox empties their contents and preserves DSM directory roots.' },
         { target: `@appshare/${pkg}, /usr/syno/etc/packages/${pkg}`, condition: 'After uninstall, if DSM leaves package infrastructure or a package-config symlink.', action: 'Administrator: inspect these package-specific paths and remove unused infrastructure; do not follow the symlink to delete shared data.' },
+        // Package scripts run as the package account; only the root executor can edit these DSM files.
+        executor
+            ? { target: `SYNO.SDS.${pkg}.Instance rules in Application Privileges`, condition: AUTOMATIC_FAILED, action: 'The root executor removes these rules automatically through the Application Privileges API on uninstall. Administrator: remove surviving rules in Control Panel > Application Privileges; DSM would apply them again to a later install under the same name.' }
+            : { target: `SYNO.SDS.${pkg}.Instance rules in Application Privileges`, condition: 'After uninstall, if this package will not be reinstalled.', action: 'DSM keeps these rules in /etc/synoappprivilege.db and applies them again to a later install under the same name. Administrator: remove them in Control Panel > Application Privileges.' },
+        ...(executor && portal ? [{ target: `${pkg} Login Portal alias`, condition: AUTOMATIC_FAILED, action: 'DSM removes the alias configuration without reloading its web server; the root executor then reloads the web server automatically. Administrator: if the alias still opens a DSM page, save an application alias in Control Panel > Login Portal > Applications to reload it, or restart the NAS.' }] : []),
         { target: `${pkg} package account/group`, condition: 'After uninstall, only if this package will not be reinstalled and the identity is unused.', action: 'Administrator: review DSM internal account/group and associated ACLs before cleanup. Package scripts do not delete system identities.' },
     ];
     if (executor)

package/dist/standalone/dsm-window.js

@@ -1,6 +1,6 @@
 import { REOPEN_EVENTS_RUNTIME } from "./reopen-events.js";
 import { DSM_LANGS } from "./i18n.js";
-import { PASSWORD_CONFIRM, ROOT_PANEL, ROOT_RUNTIME } from "./root-window.js";
+import { PASSWORD_CONFIRM, ROOT_PANEL, ROOT_RUNTIME, rootPanelCatalogs } from "./root-window.js";
 import { HOST_ADAPTER_RUNTIME } from "./host-adapter.js";
 import { permitsOrdinaryUsers } from "./api-permissions.js";
 import { PORTAL_RUNTIME } from "./portal-window.js";
@@ -297,21 +297,18 @@ ${ns}.webApi = function (win) {
 }
 const ROOT_PANEL_CSS = [
     ".dsmapp-rootpanel{margin:16px 20px;padding:12px 16px;border:1px solid #d5dce5;border-radius:4px;background:#f7f9fb;font-size:13px;line-height:1.5}",
-    ".dsmapp-rootpanel h2{margin:0 0 6px;font-size:14px;font-weight:600}",
-    ".dsmapp-rootpanel dl{display:grid;grid-template-columns:max-content 1fr;gap:2px 12px;margin:8px 0}",
-    ".dsmapp-rootpanel dt{color:#526070}.dsmapp-rootpanel dd{margin:0}",
-    ".dsmapp-rootpanel pre{margin:4px 0 8px;padding:6px 8px;background:#fff;border:1px solid #e1e6ec;white-space:pre-wrap;max-height:160px;overflow:auto}",
+    ".dsmapp-rootpanel h2{margin:0 0 6px;font-size:14px;font-weight:600}.dsmapp-rootpanel p{margin:4px 0}",
+    ".dsmapp-rootpanel label{display:block;margin:8px 0}.dsmapp-rootpanel input{margin-left:8px;padding:3px 6px}",
     ".dsmapp-rootpanel-actions button{margin-right:8px;padding:4px 14px}",
     ".dsmapp-rootpanel-primary{background:#057feb;color:#fff;border:1px solid #057feb;border-radius:3px}",
-    ".dsmapp-rootpanel-message{color:#c0392b}.dsmapp-rootpanel-hint{color:#526070;font-size:12px}",
+    ".dsmapp-rootpanel-hint{color:#526070;font-size:12px}.dsmapp-rootpanel [hidden]{display:none}",
 ].join("");
 /**
- * An install-selected delegate scope is approved only in the app's settings: the
- * approval carries the scope the administrator picks there, and the window panel
- * has no scope picker.
+ * A Vue app approves in the SDK's ExecutorSettings, which also carries an
+ * install-selected scope; the window panel serves plain-UI apps only.
  */
 function settingsOnlyApproval(manifest) {
-    return manifest.ui.build !== undefined && manifest.capabilities.delegate?.scope === "install-selected";
+    return manifest.ui.build !== undefined;
 }
 /**
  * The capabilities.rootOps: true additions to the window: the exact tasks and panel
@@ -352,7 +349,7 @@ ${PASSWORD_CONFIRM}
     });
 ${settingsOnlyApproval(manifest) ? "" : `    var panels = me.body && me.body.dom.querySelector(".dsmapp-rootpanels");
     if (panels) {
-      ${ns}.mountRootPanel(panels, access, null, ${ns}.rootTasks, session().admin);
+      ${ns}.mountRootPanel(panels, access, ${ns}.createI18n(lang, ${JSON.stringify(rootPanelCatalogs())}).t, session().admin);
     }
 `}`,
     };

package/dist/standalone/inspect-spk.js

@@ -19,7 +19,7 @@ import { renderUninstallWizardFiles } from "../build-spk/uninstall-wizard.js";
 import { renderStandaloneScript } from "./lifecycle.js";
 import { listPortExposures, loadCompose } from "../compose/analyze.js";
 import { uninstallCleanup } from "../runtime/uninstall-cleanup.js";
-import { PORTAL_JSON_RELPATH, PORTAL_MUSTACHE_RELPATH, portalResource, renderPortalJson, renderPortalLifecycle, renderPortalMustache, renderPortalWizardStep } from "../portal/package.js";
+import { PORTAL_JSON_RELPATH, PORTAL_MUSTACHE_RELPATH, renderPortalJson, renderPortalLifecycle, renderPortalMustache, renderPortalWizardStep } from "../portal/package.js";
 import { isPortalAlias } from "../portal/alias.js";
 import { defaultPackageIcons, MAX_ICON_BYTES } from "../build-spk/dsm-icons.js";
 import { decodePng } from "../build-spk/png.js";
@@ -70,7 +70,8 @@ export async function inspectSpk(spkPath, expectedKind) {
         await checkArch(dir, info, kind, paths.has(CGI_PAYLOAD_PATH), findings);
         const background = kind === "native-go" && paths.has(BACKGROUND_WORKER_PAYLOAD);
         const sharedFolder = standalone ? recoverSharedFolder(readOptional(join(dir, "scripts/postinst"))) : undefined;
-        const portal = await recoverPortal(dir, info, kind === "container" ? info.package ?? "" : `SYNO.SDS.${info.package}.Instance`, paths, payload, findings);
+        // A Compose App has no executor, so its SPK never carries a portal.
+        const portal = standalone ? await recoverPortal(dir, info, `SYNO.SDS.${info.package}.Instance`, paths, payload, findings) : undefined;
         if (portal && info.os_min_ver && OS_MIN_VER.test(info.os_min_ver) && !isDsmAtLeast(info.os_min_ver, PORTAL_MIN_DSM)) {
             findings.push(`INFO os_min_ver「${info.os_min_ver}」低於 portal 需要的 DSM ${PORTAL_MIN_DSM}；DSM 7.1.1 以錯誤 320 拒裝帶 web-config app-portal 的未簽章套件，7.2 未驗證`);
         }
@@ -80,6 +81,8 @@ export async function inspectSpk(spkPath, expectedKind) {
         if (kind === "container")
             await checkContainerExposure(dir, join(dir, "package.tgz"), findings);
         const hasExecutor = (metadata.capabilities ?? []).some(name => name === "rootOps" || name === "delegate") || paths.has("executor/executor");
+        if (standalone && portal && !hasExecutor)
+            findings.push("PORTAL_REQUIRES_EXECUTOR portal 需要 executor 層級（rootOps 或 delegate）：解除安裝後只有 root purge 能讓 nginx 停止提供別名");
         const daemon = standalone ? await checkDaemon(dir, info, paths, payload, findings, hasExecutor, background) : undefined;
         if (background)
             checkBackground(dir, info, payload, findings, hasExecutor, daemon);
@@ -104,7 +107,7 @@ export async function inspectSpk(spkPath, expectedKind) {
                         findings.push(`Executor scripts/${hook} differs from fixed lifecycle.`);
                 }
             }
-            for (const [name, text] of Object.entries(renderUninstallWizardFiles(info.package, "native", { executor: true }))) {
+            for (const [name, text] of Object.entries(renderUninstallWizardFiles(info.package, "native", { executor: true, portal: Boolean(portal) }))) {
                 if (readOptional(join(dir, "WIZARD_UIFILES", name)) !== text)
                     findings.push(`Executor WIZARD_UIFILES/${name} is missing cleanup guidance.`);
             }
@@ -130,7 +133,7 @@ export async function inspectSpk(spkPath, expectedKind) {
             ...(executor ? { executor } : {}),
             ...(portal ? { portal: { appId: portal.appId, alias: portal.alias } } : {}),
             ...(metadata.entry ? { entry: metadata.entry } : {}),
-            ...(standalone ? { uninstallCleanup: uninstallCleanup(info.package, hasExecutor) } : {}),
+            ...(standalone ? { uninstallCleanup: uninstallCleanup(info.package, { executor: hasExecutor, portal: Boolean(portal) }) } : {}),
             package: info.package,
             version: info.version,
             arch: info.arch,
@@ -324,11 +327,9 @@ function checkConf(dir, findings, kind, background, sharedFolder, pkg, portal) {
             if (!resource["docker-project"])
                 findings.push("container 缺少 docker-project resource");
             for (const key of Object.keys(resource)) {
-                if (!["docker-project", "webservice", ...(portal ? ["web-config"] : [])].includes(key))
+                if (!["docker-project", "webservice"].includes(key))
                     findings.push(`未知 container resource: ${key}`);
             }
-            if (portal && JSON.stringify(resource["web-config"]) !== JSON.stringify(portalResource()["web-config"]))
-                findings.push("container web-config 必須只有固定的 app-portal 註冊");
         }
         catch {
             findings.push("container 缺少有效的 conf/resource");

package/dist/standalone/manifest.js

@@ -11,7 +11,7 @@ import { readBackground } from "./background.js";
 import { DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_MIN_DSM, portalMinDsmMessage } from "../build-spk/dsm-version.js";
 import { readSharedFolder } from "./shared-folder.js";
 import { floorAtAdministrators, permitsOrdinaryUsers, readApiPermissions } from "./api-permissions.js";
-import { readPortalDeclaration } from "../portal/alias.js";
+import { PORTAL_REQUIRES_EXECUTOR, readPortalDeclaration } from "../portal/alias.js";
 import { renderPackageIcons } from "../build-spk/dsm-icons.js";
 import { validateReproducible } from "../reproducible-config.js";
 import { SDK_MODULE, sdkRequirement } from "../runtime/sdk-source.js";
@@ -137,7 +137,12 @@ function readManifest(raw, c) {
             permissions = readApiPermissions(backend.dir, capabilities);
         }
         catch (error) {
-            c.fail("STANDALONE_API_PERMISSIONS_INVALID", `backend/internal/api/permissions.json must define the centralized API policy: ${String(error)}`);
+            // The SDK's own routes come from its module; a failed download is not a policy problem.
+            const download = /^\[SDK_DOWNLOAD_FAILED\] ([\s\S]*)$/.exec(error.message);
+            if (download)
+                c.fail("SDK_DOWNLOAD_FAILED", download[1]);
+            else
+                c.fail("STANDALONE_API_PERMISSIONS_INVALID", `backend/internal/api/permissions.json must define the centralized API policy: ${String(error)}`);
         }
     }
     const daemon = arches && readDaemon(raw.daemon, c.root, arches, e => c.fail(e.code, e.message));
@@ -172,6 +177,9 @@ function readManifest(raw, c) {
     const icon = raw.icon === undefined ? undefined : readIcon(raw.icon, c);
     const portal = raw.portal === undefined || !packageId ? undefined : readPortalDeclaration(raw.portal, packageId)
         ?? c.fail("STANDALONE_PORTAL_INVALID", "portal 必須是 {} 或 { alias: <小寫英數與 -，1–64 字，不可為 DSM 保留路徑> }。");
+    if (portal && !capabilities.rootOps && !capabilities.delegate) {
+        c.fail("STANDALONE_PORTAL_REQUIRES_EXECUTOR", PORTAL_REQUIRES_EXECUTOR);
+    }
     if (portal && osMinVer && !isDsmAtLeast(osMinVer, PORTAL_MIN_DSM)) {
         c.fail("STANDALONE_PORTAL_MIN_DSM", portalMinDsmMessage(osMinVer, "portal"));
     }
@@ -230,7 +238,8 @@ function readEntry(value, backend, policy, c) {
     const main = backend.kind === "go" ? join(backend.dir, backend.main, "main.go") : "";
     if (backend.kind !== "go" || !sdkRequirement(backend.dir)
         || !existsSync(main) || !readFileSync(main, "utf8").includes("dsm.NewEntryGate(")) {
-        return c.fail("STANDALONE_ENTRY_UNSUPPORTED", `entry 需要 SDK 的 entry gate：backend/go.mod 要 require ${SDK_MODULE}，並在 cmd/app/main.go 以 dsm.NewEntryGate 包住 authenticator。`);
+        const shown = main ? relative(c.root, main) : "backend.main 的 main.go";
+        return c.fail("STANDALONE_ENTRY_UNSUPPORTED", `entry 需要 SDK 的 entry gate：backend/go.mod 要 require ${SDK_MODULE}，並在 ${shown} 以 dsm.NewEntryGate 包住 authenticator。`);
     }
     if (value === "app-privilege" && !permitsOrdinaryUsers(policy)) {
         return c.fail("STANDALONE_ENTRY_INVALID", "entry: app-privilege 需要至少一個 permissions.json 標為 authenticated 的 route，一般使用者才有功能可用。");

package/dist/standalone/root-window.d.ts

@@ -2,7 +2,14 @@ export { type ExecutorTask as RootTask } from '../runtime/executor-tasks.js';
 /** Exact readback is authoritative. PasswordConfirm tokens are reused immediately,
  * across both Root APIs, and never persisted (DSM validity is about 300 seconds). */
 export declare const ROOT_RUNTIME: string;
-export declare const ROOT_PANEL = "function mountRootPanel(host, access, i18n, tasks, admin) {\n  if (!admin) return;\n  var status = document.createElement(\"p\"), approve = document.createElement(\"button\"), retry = document.createElement(\"button\");\n  approve.textContent = \"Approve background access\"; retry.textContent = \"Check status\";\n  host.appendChild(status); host.appendChild(approve); host.appendChild(retry);\n  function show(result) { status.textContent = result.state + (result.reason ? \": \" + result.reason : \"\"); approve.hidden = result.state !== \"needs-admin-approval\" && result.retry !== true; }\n  function run(fn) { approve.disabled = retry.disabled = true; return fn().then(show, function(e) { show({state: \"blocked\", reason: e.message || e.code}); }).then(function() { approve.disabled = retry.disabled = false; }); }\n  access.subscribe(show);\n  approve.onclick = function() { return run(function() { return access.authorize(); }); };\n  retry.onclick = function() { return run(function() { return access.status(); }); };\n  run(function() { return access.status().then(function(result) { return result.tasks && result.tasks.boot && result.tasks.control && result.tasks.boot.state === \"ready\" && result.tasks.control.state === \"ready\" ? access.control(\"start\") : result; }); });\n}";
-/** Administrator password confirmation in the window's own session: a supplied
- * password, or a masked form when none is given. */
+type PanelLocale = "en" | "zh-TW" | "zh-CN" | "ja" | "ko" | "de" | "fr" | "es" | "it";
+/** The plain-UI window panel's text; a state's reason stays the runtime's English detail. */
+export declare const ROOT_PANEL_MESSAGES: Record<string, Record<PanelLocale, string>>;
+/** ROOT_PANEL_MESSAGES as createI18n catalogs, one per locale. */
+export declare function rootPanelCatalogs(): Record<string, Record<string, string>>;
+/** The plain-UI approval panel: it asks for the password itself and passes it
+ * to `access.authorize`, the same PasswordConfirm path as ExecutorSettings. */
+export declare const ROOT_PANEL = "function mountRootPanel(host, access, t, admin) {\n  if (!admin) return;\n  function el(tag, className) { var e = document.createElement(tag); if (className) e.className = className; return e; }\n  var panel = el(\"div\", \"dsmapp-rootpanel\"), title = el(\"h2\"), status = el(\"p\"), reason = el(\"p\", \"dsmapp-rootpanel-hint\");\n  var form = el(\"form\"), label = el(\"label\"), password = el(\"input\"), actions = el(\"div\", \"dsmapp-rootpanel-actions\");\n  var approve = el(\"button\", \"dsmapp-rootpanel-primary\"), check = el(\"button\");\n  title.textContent = t(\"title\"); label.textContent = t(\"password\");\n  password.type = \"password\"; password.autocomplete = \"current-password\";\n  approve.type = \"submit\"; approve.textContent = t(\"approve\");\n  check.type = \"button\"; check.textContent = t(\"check\");\n  label.appendChild(password); actions.appendChild(approve); actions.appendChild(check);\n  form.appendChild(label); form.appendChild(actions);\n  panel.appendChild(title); panel.appendChild(status); panel.appendChild(reason); panel.appendChild(form);\n  host.appendChild(panel);\n  function show(result) {\n    status.textContent = t(\"state.\" + result.state);\n    reason.textContent = result.reason || \"\"; reason.hidden = !result.reason;\n    label.hidden = approve.hidden = result.state !== \"needs-admin-approval\" && result.retry !== true;\n  }\n  function run(fn) { approve.disabled = check.disabled = true; return fn().then(show, function(e) { show({state: \"blocked\", reason: e.message || e.code}); }).then(function() { approve.disabled = check.disabled = false; }); }\n  access.subscribe(show);\n  form.onsubmit = function(event) {\n    if (event) event.preventDefault();\n    var entered = password.value; password.value = \"\";\n    if (!entered) return Promise.resolve();\n    return run(function() { return access.authorize(entered); });\n  };\n  check.onclick = function() { return run(function() { return access.status(); }); };\n  run(function() { return access.status().then(function(result) { return result.tasks && result.tasks.boot && result.tasks.control && result.tasks.boot.state === \"ready\" && result.tasks.control.state === \"ready\" ? access.control(\"start\") : result; }); });\n}";
+/** Administrator password confirmation in the window's own session, for the
+ * password an approval panel collected. */
 export declare const PASSWORD_CONFIRM: string;

package/dist/standalone/root-window.js

@@ -236,20 +236,61 @@ export const ROOT_RUNTIME = `function createRootAccess(options) {
     subscribe: function (listener) { listeners.push(listener); }
   };
 }`;
-export const ROOT_PANEL = `function mountRootPanel(host, access, i18n, tasks, admin) {
+/** The plain-UI window panel's text; a state's reason stays the runtime's English detail. */
+export const ROOT_PANEL_MESSAGES = {
+    title: { en: "Background access", "zh-TW": "背景存取", "zh-CN": "后台访问", ja: "バックグラウンドアクセス", ko: "백그라운드 액세스", de: "Hintergrundzugriff", fr: "Accès en arrière-plan", es: "Acceso en segundo plano", it: "Accesso in background" },
+    password: { en: "DSM administrator password", "zh-TW": "DSM 管理員密碼", "zh-CN": "DSM 管理员密码", ja: "DSM 管理者パスワード", ko: "DSM 관리자 비밀번호", de: "DSM-Administratorkennwort", fr: "Mot de passe administrateur DSM", es: "Contraseña de administrador de DSM", it: "Password amministratore DSM" },
+    approve: { en: "Approve", "zh-TW": "核准", "zh-CN": "批准", ja: "承認", ko: "승인", de: "Genehmigen", fr: "Approuver", es: "Aprobar", it: "Approva" },
+    check: { en: "Check status", "zh-TW": "檢查狀態", "zh-CN": "检查状态", ja: "状態を確認", ko: "상태 확인", de: "Status prüfen", fr: "Vérifier l'état", es: "Comprobar estado", it: "Verifica stato" },
+    "state.ready": { en: "Approved and running.", "zh-TW": "已核准，正在執行。", "zh-CN": "已批准，正在运行。", ja: "承認済みで、実行中です。", ko: "승인되었으며 실행 중입니다.", de: "Genehmigt und aktiv.", fr: "Approuvé et actif.", es: "Aprobado y en ejecución.", it: "Approvato e in esecuzione." },
+    "state.needs-admin-approval": { en: "Needs administrator approval.", "zh-TW": "需要管理員核准。", "zh-CN": "需要管理员批准。", ja: "管理者の承認が必要です。", ko: "관리자 승인이 필요합니다.", de: "Genehmigung durch einen Administrator erforderlich.", fr: "Approbation d'un administrateur requise.", es: "Requiere la aprobación de un administrador.", it: "Richiede l'approvazione di un amministratore." },
+    "state.blocked": { en: "Not available.", "zh-TW": "目前無法使用。", "zh-CN": "目前无法使用。", ja: "現在は利用できません。", ko: "현재 사용할 수 없습니다.", de: "Derzeit nicht verfügbar.", fr: "Indisponible pour le moment.", es: "No disponible por ahora.", it: "Non disponibile al momento." },
+    "state.unsupported": { en: "This DSM does not support background access.", "zh-TW": "這台 DSM 不支援背景存取。", "zh-CN": "此 DSM 不支持后台访问。", ja: "この DSM はバックグラウンドアクセスに対応していません。", ko: "이 DSM은 백그라운드 액세스를 지원하지 않습니다.", de: "Dieses DSM unterstützt keinen Hintergrundzugriff.", fr: "Ce DSM ne prend pas en charge l'accès en arrière-plan.", es: "Este DSM no admite el acceso en segundo plano.", it: "Questo DSM non supporta l'accesso in background." },
+    "state.cancelled": { en: "Approval was cancelled.", "zh-TW": "已取消核准。", "zh-CN": "已取消批准。", ja: "承認はキャンセルされました。", ko: "승인이 취소되었습니다.", de: "Genehmigung abgebrochen.", fr: "Approbation annulée.", es: "Aprobación cancelada.", it: "Approvazione annullata." },
+};
+/** ROOT_PANEL_MESSAGES as createI18n catalogs, one per locale. */
+export function rootPanelCatalogs() {
+    const out = {};
+    for (const [key, texts] of Object.entries(ROOT_PANEL_MESSAGES)) {
+        for (const [locale, text] of Object.entries(texts))
+            (out[locale] ??= {})[key] = text;
+    }
+    return out;
+}
+/** The plain-UI approval panel: it asks for the password itself and passes it
+ * to `access.authorize`, the same PasswordConfirm path as ExecutorSettings. */
+export const ROOT_PANEL = `function mountRootPanel(host, access, t, admin) {
   if (!admin) return;
-  var status = document.createElement("p"), approve = document.createElement("button"), retry = document.createElement("button");
-  approve.textContent = "Approve background access"; retry.textContent = "Check status";
-  host.appendChild(status); host.appendChild(approve); host.appendChild(retry);
-  function show(result) { status.textContent = result.state + (result.reason ? ": " + result.reason : ""); approve.hidden = result.state !== "needs-admin-approval" && result.retry !== true; }
-  function run(fn) { approve.disabled = retry.disabled = true; return fn().then(show, function(e) { show({state: "blocked", reason: e.message || e.code}); }).then(function() { approve.disabled = retry.disabled = false; }); }
+  function el(tag, className) { var e = document.createElement(tag); if (className) e.className = className; return e; }
+  var panel = el("div", "dsmapp-rootpanel"), title = el("h2"), status = el("p"), reason = el("p", "dsmapp-rootpanel-hint");
+  var form = el("form"), label = el("label"), password = el("input"), actions = el("div", "dsmapp-rootpanel-actions");
+  var approve = el("button", "dsmapp-rootpanel-primary"), check = el("button");
+  title.textContent = t("title"); label.textContent = t("password");
+  password.type = "password"; password.autocomplete = "current-password";
+  approve.type = "submit"; approve.textContent = t("approve");
+  check.type = "button"; check.textContent = t("check");
+  label.appendChild(password); actions.appendChild(approve); actions.appendChild(check);
+  form.appendChild(label); form.appendChild(actions);
+  panel.appendChild(title); panel.appendChild(status); panel.appendChild(reason); panel.appendChild(form);
+  host.appendChild(panel);
+  function show(result) {
+    status.textContent = t("state." + result.state);
+    reason.textContent = result.reason || ""; reason.hidden = !result.reason;
+    label.hidden = approve.hidden = result.state !== "needs-admin-approval" && result.retry !== true;
+  }
+  function run(fn) { approve.disabled = check.disabled = true; return fn().then(show, function(e) { show({state: "blocked", reason: e.message || e.code}); }).then(function() { approve.disabled = check.disabled = false; }); }
   access.subscribe(show);
-  approve.onclick = function() { return run(function() { return access.authorize(); }); };
-  retry.onclick = function() { return run(function() { return access.status(); }); };
+  form.onsubmit = function(event) {
+    if (event) event.preventDefault();
+    var entered = password.value; password.value = "";
+    if (!entered) return Promise.resolve();
+    return run(function() { return access.authorize(entered); });
+  };
+  check.onclick = function() { return run(function() { return access.status(); }); };
   run(function() { return access.status().then(function(result) { return result.tasks && result.tasks.boot && result.tasks.control && result.tasks.boot.state === "ready" && result.tasks.control.state === "ready" ? access.control("start") : result; }); });
 }`;
-/** Administrator password confirmation in the window's own session: a supplied
- * password, or a masked form when none is given. */
+/** Administrator password confirmation in the window's own session, for the
+ * password an approval panel collected. */
 export const PASSWORD_CONFIRM = `function createPasswordConfirm(win) {
   var versionUnsupported = ${versionUnsupported.toString()};
   function send(password, version) {
@@ -270,24 +311,8 @@ export const PASSWORD_CONFIRM = `function createPasswordConfirm(win) {
       return send(password, 1);
     });
   }
-  return function (suppliedPassword) {
-    if (typeof suppliedPassword === "string" && suppliedPassword) return auth(suppliedPassword);
-    return new Promise(function (resolve, reject) {
-      var form = document.createElement("form"), label = document.createElement("label"), input = document.createElement("input");
-      var submit = document.createElement("button"), cancel = document.createElement("button");
-      label.textContent = "Confirm your DSM administrator password";
-      input.type = "password"; input.autocomplete = "current-password"; input.required = true;
-      label.appendChild(input); form.appendChild(label);
-      submit.type = "submit"; submit.textContent = "Approve"; form.appendChild(submit);
-      cancel.type = "button"; cancel.textContent = "Cancel"; form.appendChild(cancel);
-      win.body.dom.appendChild(form); input.focus();
-      function close() { input.value = ""; if (form.parentNode) form.parentNode.removeChild(form); }
-      cancel.onclick = function () { close(); resolve({confirmed: false}); };
-      form.onsubmit = function (event) {
-        event.preventDefault(); submit.disabled = cancel.disabled = true;
-        var password = input.value; input.value = "";
-        auth(password).then(function (result) { close(); resolve(result); }, function (error) { close(); reject(error); });
-      };
-    });
+  return function (password) {
+    if (typeof password !== "string" || !password) return Promise.reject({code: "password_required"});
+    return auth(password);
   };
 }`;

package/dist/standalone/spk.js

@@ -130,7 +130,7 @@ export async function assembleStandaloneSpk(options) {
             ...install.static,
             ...install.dynamic,
             ...(folder ? renderSharedFolderUpgradeWizardFiles(manifest.package, folder) : {}),
-            ...renderUninstallWizardFiles(manifest.package, "native", { executor: Boolean(options.executor) }),
+            ...renderUninstallWizardFiles(manifest.package, "native", { executor: Boolean(options.executor), portal: Boolean(portal) }),
         });
         writePackageCenterIcons(staging, icons);
         mkdirSync(dirname(options.outputPath), { recursive: true });

package/dist/validate.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { contractSpan, makeError } from "./errors.js";
+import { getErrorCode } from "./error-registry.js";
 import { collectInstallParameters, getValuePosition, loadContract } from "./contract/load.js";
 import { validateContract } from "./contract/validate.js";
 import { findListingUnsupportedInstallTypes } from "./contract/unsupported-types.js";
@@ -30,7 +31,7 @@ export function validateProject(project, options = {}) {
         const loaded = isNativeLayout(project.root) ? loadNativeLayout(project.root) : loadStandaloneManifest(project.root);
         return loaded.ok ? { ok: true, errors: [] } : { ok: false, errors: loaded.errors.map(error => ({
                 ...error, span: { file: DSM_PACKAGE_FILENAME, line: 1, column: 1 },
-                suggestion: "請修正 dsm-package.yaml 的 schema 2 欄位與能力宣告。",
+                suggestion: getErrorCode(error.code)?.suggestion ?? "請修正 dsm-package.yaml 的 schema 2 欄位與能力宣告。",
             })) };
     }
     const parsed = loadContract(project.contractPath);