@synopackageland/cli 0.8.0 → 0.9.1

package/dist/standalone/root-window.js

@@ -1,7 +1,6 @@
 import { bootDefinition, controlDefinition } from '../runtime/executor-tasks.js';
 import { executorScopeTask } from '../runtime/executor-scope-task.js';
 import { versionUnsupported } from '../runtime/dsm-version.js';
-export { executorTasks as rootTasks } 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 const ROOT_RUNTIME = `function createRootAccess(options) {
@@ -237,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) {
@@ -271,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/sdk-check.d.ts

@@ -0,0 +1,9 @@
+export interface SdkProblem {
+    code: string;
+    message: string;
+}
+/**
+ * backend/go.mod names the App's SDK version; the frontend package and this
+ * CLI must agree with it. `needsSdk`: the App declares delegate or rootOps.
+ */
+export declare function sdkProblems(backendDir: string, frontendDir: string | undefined, needsSdk: boolean, cliVersion?: string): SdkProblem[];

package/dist/standalone/sdk-check.js

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CLI_VERSION } from "../cli-version.js";
+import { SDK_MODULE, SDK_PACKAGE, sdkRequirement } from "../runtime/sdk-source.js";
+const minorLine = (version) => version.split(".").slice(0, 2).join(".");
+/**
+ * backend/go.mod names the App's SDK version; the frontend package and this
+ * CLI must agree with it. `needsSdk`: the App declares delegate or rootOps.
+ */
+export function sdkProblems(backendDir, frontendDir, needsSdk, cliVersion = CLI_VERSION) {
+    const version = sdkRequirement(backendDir);
+    if (!version) {
+        return needsSdk ? [{ code: "SDK_REQUIRED", message: `capabilities.delegate 與 rootOps 需要 SDK：在 backend/go.mod 加入 require ${SDK_MODULE} v${minorLine(cliVersion)}.x。` }] : [];
+    }
+    const problems = [];
+    if (minorLine(version) !== minorLine(cliVersion)) {
+        problems.push({ code: "SDK_UNSUPPORTED", message: `backend/go.mod 要求 SDK ${version}；CLI ${cliVersion} 只支援 SDK ${minorLine(cliVersion)}.x。請改用對應的 CLI，或把 SDK 升到 ${minorLine(cliVersion)}.x。` });
+    }
+    const frontend = frontendDir === undefined ? undefined : frontendSdkVersion(frontendDir);
+    if (frontend && frontend.version !== version) {
+        problems.push({ code: "SDK_VERSION_MISMATCH", message: `frontend/package.json 的 ${SDK_PACKAGE} 是 ${frontend.spec}（${frontend.version ?? "讀不到版本"}），backend/go.mod 要求 ${version}；兩者必須相同。` });
+    }
+    return problems;
+}
+/** The SDK the frontend depends on: a version, or a file: checkout read through its package.json. */
+function frontendSdkVersion(frontendDir) {
+    const pkg = readJson(join(frontendDir, "package.json"));
+    const spec = pkg?.dependencies?.[SDK_PACKAGE] ?? pkg?.devDependencies?.[SDK_PACKAGE];
+    if (typeof spec !== "string")
+        return undefined;
+    if (!spec.startsWith("file:"))
+        return { spec, version: spec };
+    const version = readJson(join(resolve(frontendDir, spec.slice("file:".length)), "package.json"))?.version;
+    return { spec, version: typeof version === "string" ? version : undefined };
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/standalone/spk.js

@@ -84,7 +84,7 @@ export async function assembleStandaloneSpk(options) {
         }
         copyStandaloneNotices(manifest.root, manifest.ui.dir, join(staging, 'package'), manifest.backend.kind === 'go' || Boolean(manifest.daemon), manifest.backend.kind === 'go' ? manifest.backend.dir : undefined);
         if (manifest.daemon)
-            copyFileSync(new URL('../../templates/_shared/LICENSES/TEMPLATE.txt', import.meta.url), join(staging, 'package', 'LICENSES', 'DAEMON-LICENSE.txt'));
+            copyFileSync(new URL('../../assets/licenses/TEMPLATE.txt', import.meta.url), join(staging, 'package', 'LICENSES', 'DAEMON-LICENSE.txt'));
         const portal = nativePortal(manifest);
         if (portal) {
             writeFile(join(staging, "package", PORTAL_JSON_RELPATH), renderPortalJson(portal));
@@ -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/template-paths.d.ts

@@ -1,2 +1,7 @@
-/** Both source execution and the published CLI resolve the same bundled templates. */
-export declare function templatesRoot(): string;
+/**
+ * The scaffold templates come from the exactly pinned @synopackageland/templates
+ * package; SYNOPKGLAND_TEMPLATES_DIR points at a templates checkout instead.
+ */
+export declare function templatesRoot(env?: NodeJS.ProcessEnv, from?: string): string;
+/** Go sources the CLI builds into every SPK that needs them; they are not scaffolded. */
+export declare function goAssetDir(name: "daemon" | "gateway"): string;

package/dist/template-paths.js

@@ -1,9 +1,21 @@
-import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-/** Both source execution and the published CLI resolve the same bundled templates. */
-export function templatesRoot() {
-    const moduleDir = dirname(fileURLToPath(import.meta.url));
-    const distTemplates = join(moduleDir, "templates");
-    return existsSync(distTemplates) ? distTemplates : join(moduleDir, "..", "templates");
+/**
+ * The scaffold templates come from the exactly pinned @synopackageland/templates
+ * package; SYNOPKGLAND_TEMPLATES_DIR points at a templates checkout instead.
+ */
+export function templatesRoot(env = process.env, from = import.meta.url) {
+    if (env.SYNOPKGLAND_TEMPLATES_DIR)
+        return join(env.SYNOPKGLAND_TEMPLATES_DIR, "templates");
+    try {
+        return join(dirname(createRequire(from).resolve("@synopackageland/templates/package.json")), "templates");
+    }
+    catch {
+        throw new Error("[TEMPLATES_MISSING] @synopackageland/templates is not installed; reinstall @synopackageland/cli, or set SYNOPKGLAND_TEMPLATES_DIR to a templates checkout.");
+    }
+}
+/** Go sources the CLI builds into every SPK that needs them; they are not scaffolded. */
+export function goAssetDir(name) {
+    return fileURLToPath(new URL(`../assets/go/${name}`, import.meta.url));
 }

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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -13,16 +13,18 @@
     "dist",
     "assets",
     "CHANGELOG.md",
-    "templates",
     "schema",
     "skills"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc && node scripts/copy-templates.mjs",
+    "build": "rm -rf dist && tsc",
     "test": "npm run build && node --import tsx --test test/**/*.test.ts",
+    "test:scripts": "node --test scripts/test/release.test.mjs scripts/test/pack-docker.test.mjs scripts/test/npm-pack.test.mjs scripts/test/executor-bump.test.mjs scripts/test/smoke-exports.test.mjs scripts/test/executor-digests.test.mjs",
+    "gates": "bash scripts/ci/gate.sh npm && bash scripts/ci/gate.sh native-go && bash scripts/ci/gate.sh daemon-gateway",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@synopackageland/templates": "0.9.1",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "tar": "^7.4.3",
@@ -38,6 +40,14 @@
     "registry": "https://registry.npmjs.org"
   },
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/synopackageland/syno-pkg-land-cli.git"
+  },
+  "homepage": "https://github.com/synopackageland/syno-pkg-land-cli#readme",
+  "bugs": {
+    "url": "https://github.com/synopackageland/syno-pkg-land-cli/issues"
+  },
   "exports": {
     "./authorization-sdk": "./dist/authorization-sdk.js",
     "./dist/*": "./dist/*",

package/schema/synology-app.schema.json

@@ -151,16 +151,7 @@
               "description": "DSM group names allowed in; only with access: dsm-groups."
             },
             "portal": {
-              "type": "object",
-              "properties": {
-                "alias": {
-                  "type": "string",
-                  "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$",
-                  "description": "Default DSM Application Portal alias (https://<nas>/<alias>/). Omit to use the package name. An administrator still applies it."
-                }
-              },
-              "additionalProperties": false,
-              "description": "Register the App in DSM Control Panel > Login Portal > Applications. Needs launch: dsm-window behind the DSM gateway (access other than public) and os_min_ver 7.3.2-86009 or later. Registration alone exposes nothing."
+              "description": "Not available: a Compose App has no executor, and a Login Portal alias needs the root executor to stop nginx serving it after uninstall. validate refuses it with CONTRACT_PORTAL_REQUIRES_EXECUTOR; an administrator can set up a reverse proxy in DSM instead."
             }
           },
           "additionalProperties": true

package/skills/SKILL.md

@@ -13,7 +13,7 @@ Never install, uninstall, publish or modify NAS data without task authorization.
 
 Native projects use schema 2 capabilities and `--with files,jobs,login,root-ops,delegate`; use `add` for existing projects. Prefer `check --json`, `build --json`, `inspect <spk> --json`, `deploy --dry-run --json`, and `status --host <profile> --json` for structured results. Read the conflict policy in reference/create.md before adding overlays.
 
-Read reference/portal.md before declaring or changing a DSM Application Portal alias (`add portal`); DSM owns the saved setting. Read reference/files.md and reference/identity.md for capability boundaries. RootOps and delegate share one-time protected executor boot/control setup with digest approval. Existing native products can explicitly use the separate authorization-sdk build-time adapter; do not mix its tasks with generated executor capabilities. App sessions alone do not grant NAS file authority.
+Read reference/portal.md before declaring or changing a DSM Application Portal alias (`add portal`); DSM owns the saved setting, and only an App with rootOps or delegate may declare one. Read reference/files.md and reference/identity.md for capability boundaries. RootOps and delegate share one-time protected executor boot/control setup with digest approval. Existing native products can explicitly use the separate authorization-sdk build-time adapter; do not mix its tasks with generated executor capabilities. App sessions alone do not grant NAS file authority.
 
 Read [reference/ui-vue.md](reference/ui-vue.md) when editing Vue components in the native-go Vue template; use the installed SDK contracts, keep DSM embedding boundaries, and verify the actual app.
 

package/skills/reference/create.md

@@ -16,7 +16,7 @@ synopkgland init -t compose --from ./compose.yaml upstream-app
 
 ## 容器存取控制
 
-有 adminport 的容器 App 預設經 DSM 驗證 gateway（`integration.web.access`：dsm-users 預設、dsm-admins、dsm-groups＋groups、public）。Compose published port 必須綁 loopback：`127.0.0.1:<adminport>:<port>`，否則 check 失敗（`COMPOSE_GATEWAY_PORT_EXPOSED`）。gateway 是編譯的 Go，建置需要 Go 與 `--arch`。`public` 才保留匿名 Web Station portal，inspect 會以 `CONTAINER_ANONYMOUS_PORTAL` 提醒。
+有 adminport 的容器 App 預設經 DSM 驗證 gateway（`integration.web.access`：dsm-users 預設、dsm-admins、dsm-groups＋groups、public）。Compose published port 必須綁 loopback：`127.0.0.1:<adminport>:<port>`，否則 check 失敗（`COMPOSE_GATEWAY_PORT_EXPOSED`）。gateway 是編譯的 Go，建置需要 Go 與 `--arch`。`public` 才保留匿名 Web Station portal，inspect 會以 `CONTAINER_ANONYMOUS_PORTAL` 提醒。Compose App 沒有 executor，不能宣告 `integration.web.portal`（`CONTRACT_PORTAL_REQUIRES_EXECUTOR`）。
 
 ## 建置與檢查
 
@@ -31,7 +31,12 @@ native-go 與 binary 使用 `dsm-package.yaml` 的 `schema: 2`，backend 寫 `ki
 既有 native-go 專案用 `synopkgland add files jobs login`；已存在能力回報 no-op。overlay 檔案已有不同內容或 stub 被改動時，add 拒絕並列出衝突；不修改業務 routes 或 App.vue。
 check、inspect、build、deploy、status 支援 `--json`，stdout 只有單一 JSON 物件，錯誤包含 code、message、hint；進度在 stderr。
 
-rootOps 與 delegate 已共用管理員 PasswordConfirm 核准的 protected executor、boot/control tasks；精確 task readback 與 digest health 一致才 ready，pins 變更須重核准。native 產品另可明確 opt-in authorization-sdk adapter，不與 generated executor tasks 混用。SDK off stub 與 routes_test.go 的預設 policy scaffold 只有內容仍等於 bundled base 時才會替換；App 自訂版本拒絕。
+rootOps 與 delegate 已共用管理員 PasswordConfirm 核准的 protected executor、boot/control tasks；精確 task readback 與 digest health 一致才 ready；policy（operations、scope、root 腳本）變更須重核准，policy 不變的 executor 更新會自動 repin，install-selected 的 scope 需管理員確認一次。Vue App 只在 SDK 的 ExecutorSettings 核准；plain UI 由 DSM 視窗面板核准，兩者都在面板內輸入密碼並走 PasswordConfirm。native 產品另可明確 opt-in authorization-sdk adapter，不與 generated executor tasks 混用。SDK off stub 與 routes_test.go 的預設 policy scaffold 只有內容仍等於 bundled base 時才會替換；App 自訂版本拒絕。
+
+## 兩種層級
+
+- 無升權 App（沒有 rootOps、delegate；含所有 Compose App）：安裝、執行、解除安裝都只用套件帳號，任何階段都不用 root。不能宣告 portal（native `STANDALONE_PORTAL_REQUIRES_EXECUTOR`、Compose `CONTRACT_PORTAL_REQUIRES_EXECUTOR`）；需要登入入口別名時由管理員在 DSM 手動設定反向代理。解除安裝後 DSM 保留的「控制台」>「應用程式權限」規則由管理員手動移除，精靈與 cleanup 清單會說明。
+- executor App（rootOps 或 delegate）：解除安裝時 root purge 自動刪除 `SYNO.SDS.<package>.Instance` 的應用程式權限規則，宣告 portal 時在 DSM 移除別名後 reload nginx。精靈說明自動清除；cleanup 清單只在自動清除失敗時（系統日誌 `synopkgland-executor`）才需要管理員處理。
 
 ## Permanent destination integration
 

package/skills/reference/deploy.md

@@ -7,6 +7,6 @@
 
 Deployment uploads directly to DSM. It does not publish artifacts. Container install answers use --share, --run-as and --param; omitted upgrade answers are retained by package preinst, which also rejects missing newly required values.
 
-For native-go root-ops, approve fixed operations in DSM after installation. Updates that change the task text require fresh approval. Remove tasks before uninstall. Never delete installed packages or data as part of a code cleanup.
+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.
 
 5. After installation run `synopkgland status --host <profile> --json`; inspect every capability state and Open URL. Installation is not readiness. Delegate is implemented and shipped (default `files.moveFromStaging`); full device lifecycle acceptance is still pending for the shared delegate/rootOps executor: install → setup → reboot → upgrade → revoke → uninstall. Delete App Data is not evidence of complete cleanup; verify retained directories/account artifacts.

package/skills/reference/identity.md

@@ -2,7 +2,7 @@
 
 Native-go validates the caller's DSM session per package. Business route permissions come from backend/internal/api/permissions.json; SDK-owned route policy is protected separately. Capabilities describe execution/resources and do not grant business route access. Never trust a request username as owner.
 
-Entry: omit `entry` for legacy access; `entry: admin-only` admits administrators only and is the floor of every route: SDK routes a capability adds (files, jobs, portal, delegate, rootOps) refuse ordinary users with `admin_required`, the launcher is hidden, and an app route marked `authenticated` or `public` in permissions.json fails validate/build with `STANDALONE_ENTRY_WIDENED` (only the public `identity: standalone` login routes stay public; they admit no one by themselves). The SPK records the mode in `sdk-package.json`; `inspect` prints it and flags `ENTRY_LAUNCHER_MISMATCH`; `entry: app-privilege` also admits accounts DSM Application Privileges allows for `SYNO.SDS.<package>.Instance` (native-go only, needs an `authenticated` route). DSM evaluates user/group/everyone rules, allow/deny precedence and IP ranges; one CGI check covers every route, failures refuse with `app_privilege_denied`, and decisions are cached at most 30 seconds. DSM's install default allows administrators only, so declaring or upgrading never opens the app to everyone. The delegate executor applies the same entry rule to every protected and producer move: once DSM no longer allows a user, new moves under that user's still-valid grant are refused (`APP_DENIED`, grant invalidated); files already saved stay. Guard global settings in shared routes with Go `api.RequireAdmin(caller)` (`admin_required`); the frontend `ctx.user?.isAdmin` only hides controls.
+Entry: omit `entry` for legacy access; `entry: admin-only` admits administrators only and is the floor of every route: SDK routes a capability adds (files, jobs, portal, delegate, rootOps) refuse ordinary users with `admin_required`, the launcher is hidden, and an app route marked `authenticated` or `public` in permissions.json fails validate/build with `STANDALONE_ENTRY_WIDENED` (only the public `identity: standalone` login routes stay public; they admit no one by themselves). The SPK records the mode in `sdk-package.json`; `inspect` prints it and flags `ENTRY_LAUNCHER_MISMATCH`; `entry: app-privilege` also admits accounts DSM Application Privileges allows for `SYNO.SDS.<package>.Instance` (native-go only, needs an `authenticated` route). DSM evaluates user/group/everyone rules, allow/deny precedence and IP ranges; one CGI check covers every route, failures refuse with `app_privilege_denied`, and decisions are cached at most 30 seconds. DSM's install default allows administrators only, so declaring or upgrading never opens the app to everyone. DSM keeps those rules after uninstall and applies them again to a later install under the same name: an App with the executor (rootOps or delegate) removes them automatically at uninstall (failures go to the system log entry `synopkgland-executor`); a no-privilege App never uses root, so an administrator removes them in Control Panel > Application Privileges. The delegate executor applies the same entry rule to every protected and producer move: once DSM no longer allows a user, new moves under that user's still-valid grant are refused (`APP_DENIED`, grant invalidated); files already saved stay. Guard global settings in shared routes with Go `api.RequireAdmin(caller)` (`admin_required`); the frontend `ctx.user?.isAdmin` only hides controls.
 
 I capability: init --with login or add login enables Go-native standalone identity and Vue login. Same-host DSM cookies can be reused across ports after backend verification. Missing cookies use an HTTPS DSM account/password/OTP fallback; passwords and DSM credentials are not persisted. Plain UI is unsupported. App sessions last at most 15 minutes; sensitive operations revalidate live DSM cookies and local UID. Password-only sessions permit only basic app.status/greeting.get reads. Missing revalidation returns session_revalidation_required; files return dsm_session_required. Sign in to DSM on the same hostname. Web Station portal/proxy acceptance remains pending.
 

package/skills/reference/portal.md

@@ -1,6 +1,8 @@
 # DSM Application Portal
 
-Declare: native-go/binary `portal: {}` or `portal: {alias: my-app}` in dsm-package.yaml (`synopkgland add portal`); Compose `integration.web.portal: {}` only for a DSM-window app behind the DSM auth gateway. The alias defaults to the package name in lowercase. Aliases are 1–64 lowercase letters, digits or `-`, not starting or ending with `-`, and not a DSM path or Synology App alias (`webman`, `file`, …). The native-layout `backend: {kind: native}` owns its conf/scripts: the SDK does not register a portal for it.
+Tier: only an App with the executor (`capabilities.rootOps` or `capabilities.delegate`) may declare a portal, because after uninstall only root can make nginx stop serving the alias. A no-privilege native App fails check/build with `STANDALONE_PORTAL_REQUIRES_EXECUTOR`, `add portal` refuses it unless the same call adds `root-ops` or `delegate`, and inspect flags such an SPK with `PORTAL_REQUIRES_EXECUTOR`. A Compose App has no executor: `integration.web.portal` always fails with `CONTRACT_PORTAL_REQUIRES_EXECUTOR`. Without the executor, an administrator can set up a reverse proxy in DSM instead.
+
+Declare: native-go/binary with rootOps or delegate, `portal: {}` or `portal: {alias: my-app}` in dsm-package.yaml (`synopkgland add root-ops portal`, or `add portal` once the executor is declared). The alias defaults to the package name in lowercase. Aliases are 1–64 lowercase letters, digits or `-`, not starting or ending with `-`, and not a DSM path or Synology App alias (`webman`, `file`, …). The native-layout `backend: {kind: native}` owns its conf/scripts: the SDK does not register a portal for it.
 
 Build: the SPK carries `etc/portal.json` (every field DSM's app-portal worker needs) and `etc/portal.mustache`, `conf/resource` registers them, and the install wizard adds a prefilled alias step. preinst validates the answer; postinst stores it as the package's own draft and default alias. Nothing is active until an administrator applies it. `inspect <spk> --json` reports `portal: {appId, alias}` and refuses any other portal content.
 
@@ -8,10 +10,12 @@ Activate: DSM owns the saved setting. Administrators use the app's portal panel
 
 Read: ordinary users call the Go backend's `portal.status` (`authenticated`), which reads `/var/packages/<package>/etc/AppPortal.json` read-only, bounded (64 KiB, no symlinks, one JSON object, matching app id). Anything else is `unavailable` and the UI shows "ask an administrator". A binary CGI must implement the same `{state, alias}` answer itself or ordinary users never see the link.
 
-DSM floor: os_min_ver must be 7.3.2-86009 or later. DSM 7.1.1-42962 refuses an unsigned SPK whose conf/resource carries web-config app-portal (Package Center error 320, "non-synology-signed package should not use internal worker"); 7.3.2-86009 and 7.4 install it; 7.2 and 7.3.0/7.3.1 are untested (unknown). validate/build fail with `STANDALONE_PORTAL_MIN_DSM` / `CONTRACT_PORTAL_MIN_DSM`, `--min-dsm` cannot go below it, `add portal` raises a lower os_min_ver, and inspect flags a lower INFO os_min_ver. Fix: raise os_min_ver or remove the portal.
+DSM floor: os_min_ver must be 7.3.2-86009 or later. DSM 7.1.1-42962 refuses an unsigned SPK whose conf/resource carries web-config app-portal (Package Center error 320, "non-synology-signed package should not use internal worker"); 7.3.2-86009 and 7.4 install it; 7.2 and 7.3.0/7.3.1 are untested (unknown). validate/build fail with `STANDALONE_PORTAL_MIN_DSM`, `--min-dsm` cannot go below it, `add portal` raises a lower os_min_ver, and inspect flags a lower INFO os_min_ver. Fix: raise os_min_ver or remove the portal.
 
 Capability: beyond that floor, no version gate. The panel needs SYNO.API.Info to list `SYNO.Core.AppPortal` (v2) and the app's registration to exist; otherwise administrators get only the Control Panel shortcut.
 
 UI: plain JS calls `ctx.portal && ctx.portal.mountPanel(element)` and disposes it on unmount; Vue renders `portal/PortalSettings.vue`. `ctx.portal.messages` carries the SDK text in all nine languages.
 
-Never: write `AppPortal.json`, `@appconf/<package>` or `/usr/syno/etc/www/app.d`; add a backend route that changes the alias; relay QuickConnect responses or build QuickConnect links; reboot or change other packages' portal entries while testing. DSM keeps the alias across upgrades and removes the entry on uninstall.
+Never: write `AppPortal.json`, `@appconf/<package>` or `/usr/syno/etc/www/app.d`; add a backend route that changes the alias; relay QuickConnect responses or build QuickConnect links; reboot or change other packages' portal entries while testing. DSM keeps the alias across upgrades and removes the entry on uninstall, but it does not reload nginx, and it keeps the App's Application Privileges rules.
+
+Uninstall: the root executor's purge deletes the rules of `SYNO.SDS.<package>.Instance` through the Application Privileges API and, once DSM has removed the alias files, reloads nginx (`synosystemctl reload nginx`), so the alias stops at once. Failures are only logged to the system log entry `synopkgland-executor`; then an administrator saves an alias in Control Panel > Login Portal > Applications (which reloads nginx) or restarts the NAS, and removes the rules in Control Panel > Application Privileges. The uninstall wizard and the `status`/`inspect` cleanup list say this in that order: automatic first, manual only as the fallback.