@synopackageland/cli 0.6.0 → 0.7.0

package/dist/deploy/spk-version.js

@@ -18,7 +18,7 @@ export function nextDeployVersion(version, installed) {
                 break;
         }
         if (order < 0)
-            throw new Error(`Refusing downgrade from ${installed} to ${version}`);
+            throw new Error(`[DEPLOY_VERSION_INVALID] Refusing downgrade from ${installed} to ${version}`);
         if (order === 0)
             build = Math.max(build, Number(previous[2] ?? 0) + 1);
     }

package/dist/error-registry.js

@@ -1,4 +1,9 @@
 export const ERROR_REGISTRY = {
+    "NATIVE_LAYOUT_INVALID": {
+        code: "NATIVE_LAYOUT_INVALID",
+        description: "native layout 的 manifest、hook、toolkit 或產物違反 package-only 契約。",
+        suggestion: "使用 schema 2 與 backend.kind: native；檢查路徑、ELF 連結與 checksum pin。"
+    },
     "COMPOSE_ROUTE_UNSUPPORTED": {
         "code": "COMPOSE_ROUTE_UNSUPPORTED",
         "description": "Compose 沒有可用的 DSM resource worker 執行路徑。",
@@ -54,6 +59,16 @@ 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_ACCESS_INVALID": {
         "code": "CONTRACT_ACCESS_INVALID",
         "description": "integration.web.access 模式無效。",
@@ -111,13 +126,13 @@ export const ERROR_REGISTRY = {
     },
     "CONTRACT_SECRET_UNSUPPORTED": {
         "code": "CONTRACT_SECRET_UNSUPPORTED",
-        "description": "install.<NAME>.type: secret 目前沒有可用的安裝路徑。2026-08-27 於 vt-nas 實測：無論是否在 Compose 引用，Package Center 安裝都以 DSM broken／150 結束且不建立 Container Manager project（同一台 NAS 上無參數的對照套件正常安裝）。",
-        "suggestion": "請改用 type: string（非敏感值），或把敏感值改成 App 啟動後自行取得／由管理員放進 ${SYNO_APP_SECRETS_DIR} 的檔案。secret 型別要能用，需要先讓 DSM worker 的失敗原因可觀測（見 STATUS.md A22／A45）。"
+        "description": "install.<NAME>.type: secret 目前沒有可用的安裝路徑：無論是否在 Compose 引用，Package Center 安裝都以 DSM broken／150 結束，且不建立 Container Manager project。",
+        "suggestion": "請改用 type: string（非敏感值），或把敏感值改成 App 啟動後自行取得／由管理員放進 ${SYNO_APP_SECRETS_DIR} 的檔案。在 DSM worker 的失敗原因可觀測之前，secret 型別不會開放。"
     },
     "CONTRACT_HOMES_UNSUPPORTED": {
         "code": "CONTRACT_HOMES_UNSUPPORTED",
-        "description": "install.<NAME>.type: homes 目前沒有可用的安裝路徑。2026-08-27 於 vt-nas 實測：wizard 不產生輸入控制項，Package Center 安裝以 DSM broken／150 結束；CLI deploy 能解析出 /volume1/homes，但 DSM 於 compound install 回 4540 拒絕。",
-        "suggestion": "若 App 需要一個由管理員選定的資料夾，請改用 type: shared_folder。homes 型別要能用，需要補齊 wizard 控制項與 preinst materialization（見 STATUS.md A46）。"
+        "description": "install.<NAME>.type: homes 目前沒有可用的安裝路徑：安裝精靈不產生輸入控制項，Package Center 安裝以 DSM broken／150 結束；CLI deploy 能解析出 /volume1/homes，但 DSM 於 compound install 回 4540 拒絕。",
+        "suggestion": "若 App 需要一個由管理員選定的資料夾，請改用 type: shared_folder。在補齊安裝精靈控制項與 preinst 路徑解析之前，homes 型別不會開放。"
     },
     "INSTALL_PARAMETER_UNREFERENCED": {
         "code": "INSTALL_PARAMETER_UNREFERENCED",
@@ -467,7 +482,7 @@ export const ERROR_REGISTRY = {
     "STANDALONE_ARCHES_INVALID": {
         "code": "STANDALONE_ARCHES_INVALID",
         "description": "arches 不合法。",
-        "suggestion": "請列出不重複的 x86_64 或 aarch64，至少一個。"
+        "suggestion": "請列出不重複的 x86_64、aarch64 或 armv7，至少一個。"
     },
     "STANDALONE_ARCH_NOT_DECLARED": {
         "code": "STANDALONE_ARCH_NOT_DECLARED",
@@ -501,8 +516,8 @@ export const ERROR_REGISTRY = {
     },
     "STANDALONE_BINARY_NOT_ELF": {
         "code": "STANDALONE_BINARY_NOT_ELF",
-        "description": "backend 執行檔不是 64-bit little-endian Linux ELF。",
-        "suggestion": "請提供為 Linux 編譯的 x86_64 或 aarch64 執行檔。"
+        "description": "backend 執行檔不是該架構需要的 little-endian Linux ELF（x86_64、aarch64 為 64-bit，armv7 為 32-bit）。",
+        "suggestion": "請提供為 Linux 編譯的 x86_64、aarch64 或 armv7 執行檔。"
     },
     "STANDALONE_BINARY_ARCH_MISMATCH": {
         "code": "STANDALONE_BINARY_ARCH_MISMATCH",
@@ -569,6 +584,11 @@ export const ERROR_REGISTRY = {
         "description": "go build 失敗。",
         "suggestion": "請在 backend 目錄執行 go build ./... 並修正錯誤。"
     },
+    "STANDALONE_PORTAL_INVALID": {
+        "code": "STANDALONE_PORTAL_INVALID",
+        "description": "dsm-package.yaml 的 portal 格式或 alias 不正確。",
+        "suggestion": "請使用 portal: {} 或 portal: { alias: my-app }；alias 為 1–64 個小寫英數字或 -，且不是 DSM 保留路徑。"
+    },
     "STANDALONE_I18N_INVALID": {
         "code": "STANDALONE_I18N_INVALID",
         "description": "dsm-package.yaml 的 i18n 設定不合法。",
@@ -624,6 +644,8 @@ 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["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。" };
@@ -636,10 +658,9 @@ ERROR_REGISTRY["SPK_INSPECTION_FAILED"] = { "code": "SPK_INSPECTION_FAILED", "de
 ERROR_REGISTRY["IMAGE_PIN_REQUIRED"] = { "code": "IMAGE_PIN_REQUIRED", "description": "映像 digest 尚未固定。", "suggestion": "執行 images pin。" };
 ERROR_REGISTRY["INIT_TEMPLATE_REQUIRED"] = { "code": "INIT_TEMPLATE_REQUIRED", "description": "未指定模板。", "suggestion": "使用 -t native-go、binary 或 compose。" };
 ERROR_REGISTRY["INIT_TEMPLATE_UNKNOWN"] = { "code": "INIT_TEMPLATE_UNKNOWN", "description": "未知模板。", "suggestion": "使用 -t native-go、binary 或 compose。" };
-ERROR_REGISTRY["CLI_ARCH_INVALID"] = { "code": "CLI_ARCH_INVALID", "description": "架構選項不合法。", "suggestion": "使用 x86_64 或 aarch64。" };
-ERROR_REGISTRY["NATIVE_ARCH_UNDETERMINED"] = { "code": "NATIVE_ARCH_UNDETERMINED", "description": "無法判定 NAS 架構。", "suggestion": "指定 --arch x86_64 或 aarch64。" };
+ERROR_REGISTRY["CLI_ARCH_INVALID"] = { "code": "CLI_ARCH_INVALID", "description": "架構選項不合法。", "suggestion": "使用 x86_64、aarch64 或 armv7（armv7 用於 native-go 與 binary，不用於 Container Manager App）。" };
+ERROR_REGISTRY["NATIVE_ARCH_UNDETERMINED"] = { "code": "NATIVE_ARCH_UNDETERMINED", "description": "無法判定 NAS 架構。", "suggestion": "指定 --arch x86_64、aarch64 或 armv7。" };
 ERROR_REGISTRY["DEVELOPMENT_INSTANCE_UNSUPPORTED"] = { "code": "DEVELOPMENT_INSTANCE_UNSUPPORTED", "description": "原生專案不支援 --dev。", "suggestion": "init 時指定不同 package ID。" };
-ERROR_REGISTRY["INIT_TEMPLATE_INVALID"] = { "code": "INIT_TEMPLATE_INVALID", "description": "未知模板。", "suggestion": "使用 -t native-go、binary 或 compose。" };
 ERROR_REGISTRY["INIT_OPTIONS_UNSUPPORTED"] = { "code": "INIT_OPTIONS_UNSUPPORTED", "description": "選項不適用於這個模板。", "suggestion": "--from 僅 compose；--ui 僅 native-go。" };
 ERROR_REGISTRY["INIT_TARGET_NOT_EMPTY"] = { "code": "INIT_TARGET_NOT_EMPTY", "description": "init 目錄已有衝突檔案。", "suggestion": "使用空目錄；既有專案新增能力使用 add。" };
 ERROR_REGISTRY["INIT_COMPOSE_INVALID"] = { "code": "INIT_COMPOSE_INVALID", "description": "匯入的 Compose 不合法。", "suggestion": "--from 指向有 services 的 YAML 檔案。" };
@@ -657,10 +678,22 @@ ERROR_REGISTRY["CLI_OPTION_ARGUMENT_MISSING"] = { "code": "CLI_OPTION_ARGUMENT_M
 ERROR_REGISTRY["CLI_COMMAND_UNKNOWN"] = { "code": "CLI_COMMAND_UNKNOWN", "description": "未知指令。", "suggestion": "使用 synopkgland --help 查看指令。" };
 ERROR_REGISTRY["COMMAND_FAILED"] = { "code": "COMMAND_FAILED", "description": "指令執行失敗。", "suggestion": "查看 message 與 stderr，修正問題後重試。" };
 ERROR_REGISTRY["DEPLOY_PLAN_INVALID"] = { "code": "DEPLOY_PLAN_INVALID", "description": "部署計畫與 runtime 不符。", "suggestion": "重新 check 並產生部署計畫。" };
-ERROR_REGISTRY["DEPLOY_ARCH_UNDETERMINED"] = { "code": "DEPLOY_ARCH_UNDETERMINED", "description": "無法判定 NAS 架構。", "suggestion": "使用 --arch x86_64 或 aarch64。" };
+ERROR_REGISTRY["DEPLOY_ARCH_UNDETERMINED"] = { "code": "DEPLOY_ARCH_UNDETERMINED", "description": "無法判定 NAS 架構。", "suggestion": "使用 --arch x86_64、aarch64 或 armv7。" };
+ERROR_REGISTRY["CONTAINER_ARCH_UNSUPPORTED"] = { "code": "CONTAINER_ARCH_UNSUPPORTED", "description": "Container Manager App 只支援 x86_64 與 aarch64；DSM 不為 armv7 提供 Container Manager。", "suggestion": "改用 --arch x86_64 或 aarch64，或改用 native-go 模板。" };
 ERROR_REGISTRY["DEPLOY_BUILD_OUTPUT_INVALID"] = { "code": "DEPLOY_BUILD_OUTPUT_INVALID", "description": "部署建置輸出數量不符。", "suggestion": "指定單一架構並重新 build。" };
 export function getErrorCode(code) {
     return ERROR_REGISTRY[code];
 }
-for (const code of ["EXECUTOR_BUILD_FAILED", "EXECUTOR_PIN_REQUIRED", "EXECUTOR_POLICY", "EXECUTOR_PACKAGE", "EXECUTOR_DIGEST", "EXECUTOR_TASK_PERCENT", "EXECUTOR_TASK_LENGTH"])
-    ERROR_REGISTRY[code] = { code, description: "Executor build or pinned task definition is invalid.", suggestion: "Check manifest capabilities and executor compiler output; rebuild before administrator approval." };
+for (const [code, description, suggestion] of [
+    ["EXECUTOR_BUILD_FAILED", "executor 或 lifecycle helper 編譯失敗，或 CLI 套件缺少 executor 原始碼。", "確認已安裝 Go，查看訊息中的編譯器輸出；原始碼缺少時重新安裝 CLI。"],
+    ["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 字）。"],
+    ["EXECUTOR_DIGEST", "executor 或 policy 的 sha256 pin 格式不合法。", "重新 build，讓 CLI 重新計算 pin；不要手改 SPK 內的 pin。"],
+    ["EXECUTOR_TASK_PERCENT", "root task 腳本含有 %，DSM 工作排程器無法保存。", "從 root/ 腳本移除 % 字元（例如 date 格式改用其他寫法）。"],
+    ["EXECUTOR_TASK_LENGTH", "root task 腳本超過 DSM 工作排程器的長度上限。", "縮短 root/ 腳本，把邏輯移到套件內的檔案再由腳本呼叫。"],
+])
+    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。" };

package/dist/host/dsm-client.d.ts

@@ -1,4 +1,5 @@
 import type { HostCredentials, NasHost } from "./types.js";
+import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
 export interface CreateNasHostOptions {
     host?: string;
     credentials?: HostCredentials;
@@ -17,9 +18,12 @@ declare function synoagentcli(args: string[], profileName?: string): {
 export declare function homesPathFromDsmUserHomeRead(result: Pick<ReturnType<typeof synoagentcli>, "status" | "stdout">): string | undefined;
 /**
  * DSM reports the CPU vendor, not the ISA. Every x86_64 platform Synology
- * ships is Intel or AMD; every aarch64 one is Realtek, Marvell, Annapurna or
- * Rockchip. An unrecognised vendor returns undefined so `deploy` asks for
- * `--arch` rather than guessing wrong and building an unusable SPK.
+ * ships is Intel or AMD; the aarch64 ones are Realtek (rtd1296, rtd1619b) and
+ * Rockchip; Annapurna Labs is DSM 7's alpine/alpine4k, which are armv7 (DS416
+ * reports "ANNAPURNALABS"). Marvell makes both armada37xx (aarch64) and
+ * armada38x (armv7), so it, like an unrecognised vendor, returns undefined and
+ * `deploy` asks for `--arch` rather than guessing wrong and building an
+ * unusable SPK.
  */
-export declare function archFamilyForCpuVendor(vendor: string | undefined): "x86_64" | "aarch64" | undefined;
+export declare function archFamilyForCpuVendor(vendor: string | undefined): NativeArchFamily | undefined;
 export {};

package/dist/host/dsm-client.js

@@ -275,17 +275,23 @@ function createDsmNasHost(credentials, profileName) {
 }
 /**
  * DSM reports the CPU vendor, not the ISA. Every x86_64 platform Synology
- * ships is Intel or AMD; every aarch64 one is Realtek, Marvell, Annapurna or
- * Rockchip. An unrecognised vendor returns undefined so `deploy` asks for
- * `--arch` rather than guessing wrong and building an unusable SPK.
+ * ships is Intel or AMD; the aarch64 ones are Realtek (rtd1296, rtd1619b) and
+ * Rockchip; Annapurna Labs is DSM 7's alpine/alpine4k, which are armv7 (DS416
+ * reports "ANNAPURNALABS"). Marvell makes both armada37xx (aarch64) and
+ * armada38x (armv7), so it, like an unrecognised vendor, returns undefined and
+ * `deploy` asks for `--arch` rather than guessing wrong and building an
+ * unusable SPK.
  */
 export function archFamilyForCpuVendor(vendor) {
     const normalized = (vendor ?? "").trim().toLowerCase();
     if (normalized === "intel" || normalized === "amd") {
         return "x86_64";
     }
-    if (["realtek", "marvell", "annapurna labs", "annapurna", "rockchip"].includes(normalized)) {
+    if (["realtek", "rockchip"].includes(normalized)) {
         return "aarch64";
     }
+    if (["annapurnalabs", "annapurna labs", "annapurna"].includes(normalized)) {
+        return "armv7";
+    }
     return undefined;
 }

package/dist/host/types.d.ts

@@ -2,6 +2,7 @@ import type { SharePermissionListing } from "../deploy/share-permission-prefligh
 import type { InstalledPackageState } from "./catalog-install.js";
 import type { PortInfoEntry } from "./port-info.js";
 import type { DsmPortProfileInventory } from "./dsm-port-profile.js";
+import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
 export interface DeployIdentity {
     packageId: string;
     displayname: string;
@@ -33,7 +34,7 @@ export interface NasHost {
         executor_digest: string;
         policy_digest: string;
     } | undefined>;
-    getArchFamily?(): Promise<"x86_64" | "aarch64" | undefined>;
+    getArchFamily?(): Promise<NativeArchFamily | undefined>;
     /** List the current logical Shared Folder names using an administrator session. */
     listShareNames?(): Promise<string[]>;
     resolveSharePath?(logicalName: string): Promise<string | undefined>;

package/dist/info.js

@@ -5,7 +5,8 @@ import { appOriginFromContract } from "./host/open-url.js";
 import { resolveDeployIdentity } from "./deploy/identity.js";
 import { loadStandaloneManifest, } from "./standalone/manifest.js";
 import { inspectSpk } from "./standalone/inspect-spk.js";
-import { executorPolicy } from "./runtime/executor-policy.js";
+import { executorPolicy, executorPolicyText, sha256 } from "./runtime/executor-policy.js";
+import { executorTasks } from "./runtime/executor-tasks.js";
 import { uninstallCleanup } from "./runtime/uninstall-cleanup.js";
 export async function projectInfo(options) {
     const identity = resolveDeployIdentity(options.project, { dev: options.dev });
@@ -63,6 +64,21 @@ export function classifyRootTasks(expected, inventory) {
         ? result("needs-admin-approval", "Approve missing or outdated root tasks in the DSM package UI.")
         : result("ready", "Boot and control tasks match the executor and policy digests. Executor health must be checked in the App window.");
 }
+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));
+        if (classified.state !== "ready")
+            return classified;
+        const observed = await host.getExecutorStatus?.(m.package);
+        if (observed?.ready !== true || observed.policy_digest !== policyDigest)
+            return { ...classified, state: "blocked", reason: "Executor health or policy digest readback could not be verified." };
+        return { ...classified, reason: "Root tasks and the running executor match the source policy (no local SPK, so executor bytes were not compared)." };
+    }
+    catch {
+        return { name: "rootOps", state: "blocked", reason: "DSM executor or root task readback could not be verified." };
+    }
+}
 async function rootCapability(m, host, version) {
     const blocked = (reason) => ({
         name: "rootOps",
@@ -82,7 +98,7 @@ async function rootCapability(m, host, version) {
         return blocked("NAS architecture cannot be matched to the local executor SPK artifact.");
     const spk = join(m.root, "dist", `${m.package}-${version}-${arch}.spk`);
     if (!existsSync(spk))
-        return blocked("Built executor SPK artifact is unavailable; build this installed version first.");
+        return liveRootCapability(m, host);
     try {
         const inspected = await inspectSpk(spk);
         if (inspected.findings.length ||

package/dist/init.d.ts

@@ -1,8 +1,11 @@
+import { type CapabilityName } from "./capabilities.js";
 import type { TemplateName } from "./types.js";
 /** The container templates need DSM 7.2.1 or later; native-go and binary need 7.1. */
 export declare function isContainerTemplate(template: TemplateName): boolean;
 export declare function isTemplateName(value: string): value is TemplateName;
 export declare function listTemplates(): TemplateName[];
+/** New native scaffolds opt in explicitly; existing manifests are never migrated. */
+export declare function nativeCapabilitySettings(names: readonly CapabilityName[]): Record<string, unknown>;
 export interface InitOptions {
     /** os_min_ver of the new project: a release (7.2) or a full 7.x-build; default is the template's (DSM 7.1 for native-go/binary, DSM 7.2.1 for container templates). */
     minDsm?: string;

package/dist/init.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
-import { parse, stringify } from "yaml";
+import { isMap, isScalar, parse, parseDocument, stringify } from "yaml";
 import { capabilityNames, capabilitySettings } from "./capabilities.js";
+import { MOVE_FROM_STAGING } from './runtime/delegate-contract.js';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, join, relative } from "node:path";
 import { templatesRoot } from "./template-paths.js";
@@ -25,6 +26,15 @@ export function isTemplateName(value) {
 export function listTemplates() {
     return [...TEMPLATE_NAMES];
 }
+/** New native scaffolds opt in explicitly; existing manifests are never migrated. */
+export function nativeCapabilitySettings(names) {
+    const settings = capabilitySettings(names);
+    if (names.includes('delegate'))
+        settings.delegate = {
+            scope: 'install-selected', operations: [MOVE_FROM_STAGING], destinations: ['save'], lifetime: 'until-revoked',
+        };
+    return settings;
+}
 /**
  * native-go --with root-ops: files laid over the native-go template, and the
  * files they replace.
@@ -85,10 +95,12 @@ function isTemplateBuildArtifact(path) {
 }
 export function initFromTemplate(template, targetDir, options = {}) {
     if (!isTemplateName(template))
-        throw new Error(`[INIT_TEMPLATE_INVALID] 未知模板：${template}`);
+        throw new Error(`[INIT_TEMPLATE_UNKNOWN] 未知模板：${template}`);
     const caps = capabilityNames(options.with ?? []);
     if (caps.includes("login") && resolvedUi(template, options) === "plain")
         throw new Error("[CAPABILITY_COMBINATION_INVALID] login 需要獨立登入頁；plain UI 不支援，請改用 --ui vue。");
+    if (caps.includes("delegate") && resolvedUi(template, options) === "plain")
+        throw new Error("[CAPABILITY_COMBINATION_INVALID] delegate 的 install-selected scope 只能在 Vue 面板確認；plain UI 不支援，請改用 --ui vue。");
     if (options.from && template !== "compose")
         throw new Error("[INIT_OPTIONS_UNSUPPORTED] --from 只適用於 compose。");
     if (caps.length && template !== "native-go")
@@ -194,20 +206,11 @@ export function initFromTemplate(template, targetDir, options = {}) {
     if (template !== "compose") {
         const path = join(targetDir, "dsm-package.yaml");
         const raw = parse(readFileSync(path, "utf8"));
-        raw.capabilities = capabilitySettings(caps);
-        writeFileSync(path, stringify(raw));
-    }
-    if (template === "compose" && options.from) {
-        const imported = readFileSync(options.from, "utf8");
-        const compose = parse(imported);
-        if (!compose || typeof compose !== "object" || !compose.services)
-            throw new Error("[INIT_COMPOSE_INVALID] --from 需要包含 services 的 Compose YAML。");
-        writeFileSync(join(targetDir, "compose.yaml"), imported);
-        const path = join(targetDir, "synology-app.yaml");
-        const raw = parse(readFileSync(path, "utf8"));
-        delete raw.install;
+        raw.capabilities = nativeCapabilitySettings(caps);
         writeFileSync(path, stringify(raw));
     }
+    if (template === "compose" && options.from)
+        importCompose(options.from, targetDir, options);
     if (template === "binary") {
         mkdirSync(join(targetDir, "prebuilt"), { recursive: true });
         for (const [arch, goarch] of [["x86_64", "amd64"], ["aarch64", "arm64"]]) {
@@ -221,6 +224,35 @@ export function initFromTemplate(template, targetDir, options = {}) {
         writeFileSync(manifest, readFileSync(manifest, "utf8") + sharedFolderYaml(options.sharedFolder));
     }
 }
+/**
+ * --from replaces the example Compose. The manifest takes the requested (or
+ * directory-derived) identity and keeps only the example install entries the
+ * imported Compose references as `${KEY}` (or `${KEY_UID}`／`${KEY_GID}`).
+ */
+function importCompose(from, targetDir, options) {
+    const imported = readFileSync(from, "utf8");
+    const compose = parse(imported);
+    if (!compose || typeof compose !== "object" || !compose.services)
+        throw new Error("[INIT_COMPOSE_INVALID] --from 需要包含 services 的 Compose YAML。");
+    writeFileSync(join(targetDir, "compose.yaml"), imported);
+    const path = join(targetDir, "synology-app.yaml");
+    const doc = parseDocument(readFileSync(path, "utf8"));
+    doc.set("package", options.packageId ?? defaultPackageId(targetDir));
+    doc.set("displayname", validDisplayName(options.displayName ?? defaultDisplayName(targetDir)));
+    const install = doc.get("install");
+    const referenced = new Set([...imported.matchAll(/\$\{([A-Z][A-Z0-9_]*?)(?:_UID|_GID)?\}/g)].map(match => match[1]));
+    if (isMap(install))
+        install.items = install.items.filter(item => referenced.has(String(isScalar(item.key) ? item.key.value : item.key)));
+    if (!isMap(install) || install.items.length === 0)
+        doc.delete("install");
+    writeFileSync(path, String(doc));
+}
+function validDisplayName(displayName) {
+    if (displayName.trim() === "" || /[\r\n"\\]/.test(displayName)) {
+        throw new Error("[INIT_DISPLAY_NAME_INVALID] 顯示名稱必須是單行，且不含 \" 或 \\。");
+    }
+    return displayName;
+}
 /** The `install.sharedFolder` block, validated by the same reader build-spk uses. */
 function sharedFolderYaml(options) {
     const folder = { mode: options.mode, key: options.key ?? "shared", ...(options.name === undefined ? {} : { name: options.name }), permission: options.permission ?? "rw" };
@@ -243,15 +275,14 @@ function substitutionsFor(template, targetDir, options) {
     if (options.ui !== undefined && !["plain", "vue"].includes(options.ui))
         throw new Error("[INIT_UI_INVALID] --ui 只接受 plain 或 vue。");
     if (!SUBSTITUTED[template]) {
+        if (options.from && options.displayName !== undefined)
+            validDisplayName(options.displayName);
         return {};
     }
     const packageId = options.packageId ?? defaultPackageId(targetDir);
     if (!PACKAGE_ID.test(packageId)) {
         throw new Error(`[INIT_PACKAGE_INVALID] package「${packageId}」必須以英文字母開頭，只含英數字（2–64 字），例如 PhotoTagger。`);
     }
-    const displayName = options.displayName ?? defaultDisplayName(targetDir);
-    if (displayName.trim() === "" || /[\r\n"\\]/.test(displayName)) {
-        throw new Error("[INIT_DISPLAY_NAME_INVALID] 顯示名稱必須是單行，且不含 \" 或 \\。");
-    }
+    const displayName = validDisplayName(options.displayName ?? defaultDisplayName(targetDir));
     return { __PACKAGE__: packageId, __DISPLAY_NAME__: displayName, __BACKGROUND_ENABLED__: caps.includes("jobs") || caps.includes("delegate") ? "true" : "false" };
 }

package/dist/package-metadata.d.ts

@@ -0,0 +1,21 @@
+/** Plain text, or a map from a BCP-47 tag (en, zh-TW, ...) to plain text. */
+export type LocalizedText = string | Record<string, string>;
+export interface PackageMetadata {
+    long_description?: LocalizedText;
+    changelog?: LocalizedText;
+    contact_email?: string;
+    support_email?: string;
+    homepage?: string;
+    source_url?: string;
+    issues_url?: string;
+    license?: string;
+    maintainer_url?: string;
+    distributor?: string;
+    distributor_url?: string;
+    support_url?: string;
+    helpurl?: string;
+    screenshots?: string[];
+}
+export declare function safeMetadataUrl(value: unknown, mail?: boolean): value is string;
+export declare function validateMetadata(raw: unknown): PackageMetadata;
+export declare function metadataInfoFields(metadata?: PackageMetadata): [string, string][];

package/dist/package-metadata.js

@@ -0,0 +1,101 @@
+export function safeMetadataUrl(value, mail = false) {
+    if (typeof value !== "string" || value.length > 2048)
+        return false;
+    try {
+        const u = new URL(value);
+        return (!u.username &&
+            !u.password &&
+            (["https:", "http:"].includes(u.protocol) ||
+                (mail &&
+                    u.protocol === "mailto:" &&
+                    /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(u.pathname))));
+    }
+    catch {
+        return false;
+    }
+}
+export function validateMetadata(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("invalid metadata");
+    const allowed = [
+        "long_description",
+        "changelog",
+        "contact_email",
+        "support_email",
+        "homepage",
+        "source_url",
+        "issues_url",
+        "license",
+        "maintainer_url",
+        "distributor",
+        "distributor_url",
+        "support_url",
+        "helpurl",
+        "screenshots",
+    ];
+    for (const [k, v] of Object.entries(raw)) {
+        if (!allowed.includes(k))
+            throw new Error("unknown metadata");
+        if (k === "screenshots") {
+            if (!Array.isArray(v) ||
+                v.length > 12 ||
+                !v.every((u) => safeMetadataUrl(u)))
+                throw new Error("invalid screenshots");
+        }
+        else if ((k === "long_description" || k === "changelog") &&
+            typeof v === "object" &&
+            v &&
+            !Array.isArray(v)) {
+            if (Object.entries(v).length > 32 ||
+                !Object.entries(v).every(([lang, t]) => /^[a-z]{2}(?:-[A-Za-z]{2})?$/.test(lang) &&
+                    typeof t === "string" &&
+                    t.length <= 16000 &&
+                    !/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(t)))
+                throw new Error("invalid localized description");
+        }
+        else if (typeof v !== "string" ||
+            v.length > 16000 ||
+            /[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(v))
+            throw new Error("invalid text");
+        if (k.endsWith("_email") &&
+            (typeof v !== "string" || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v)))
+            throw new Error("invalid email");
+        if ([
+            "homepage",
+            "source_url",
+            "issues_url",
+            "maintainer_url",
+            "distributor_url",
+            "support_url",
+            "helpurl",
+        ].includes(k) &&
+            !safeMetadataUrl(v, k === "support_url"))
+            throw new Error("invalid metadata URL");
+    }
+    if (JSON.stringify(raw).length > 32000)
+        throw new Error("metadata too large");
+    return raw;
+}
+export function metadataInfoFields(metadata) {
+    if (!metadata)
+        return [];
+    const m = validateMetadata(metadata), fields = [];
+    // INFO has one changelog; a per-language map contributes its English text.
+    const changelog = typeof m.changelog === "object"
+        ? (m.changelog.en ?? Object.values(m.changelog)[0])
+        : m.changelog;
+    for (const [k, v] of [
+        ["maintainer_url", m.maintainer_url],
+        ["distributor", m.distributor],
+        ["distributor_url", m.distributor_url],
+        ["support_url", m.support_url],
+        ["helpurl", m.helpurl],
+        ["changelog", changelog],
+    ])
+        if (v)
+            fields.push([k, v.replace(/\r?\n/g, " · ")]);
+    if (!m.support_url && m.support_email)
+        fields.push(["support_url", "mailto:" + m.support_email]);
+    fields.push(["spk_land_metadata", JSON.stringify(m)]);
+    return fields;
+}

package/dist/portal/alias.d.ts

@@ -0,0 +1,25 @@
+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
+ * directory names (4102) and aliases another App uses (4103); the SDK keeps a
+ * stricter, URL-safe rule so the same value works in links and shell scripts.
+ */
+export declare const PORTAL_ALIAS_PATTERN: RegExp;
+export declare const PORTAL_ALIAS_MAX = 64;
+/**
+ * Names DSM already serves: /usr/syno/synoman entries and the default aliases
+ * of Synology Apps, as observed on DSM 7.4-90069. DSM stays the authority.
+ */
+export declare const RESERVED_PORTAL_ALIASES: readonly string[];
+export interface PortalDeclaration {
+    alias: string;
+}
+export declare function isPortalAlias(value: unknown): value is string;
+/** The package name as a slug; a reserved or too long name falls back to a stable hash. */
+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

@@ -0,0 +1,48 @@
+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
+ * directory names (4102) and aliases another App uses (4103); the SDK keeps a
+ * stricter, URL-safe rule so the same value works in links and shell scripts.
+ */
+export const PORTAL_ALIAS_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+export const PORTAL_ALIAS_MAX = 64;
+/**
+ * Names DSM already serves: /usr/syno/synoman entries and the default aliases
+ * of Synology Apps, as observed on DSM 7.4-90069. DSM stays the authority.
+ */
+export const RESERVED_PORTAL_ALIASES = [
+    "dsfile", "indexdb", "mobile", "oauth", "scripts", "sharing", "ssdp", "synosdsjslib", "synohdpack", "webapi", "webman",
+    "calendar", "chatplus", "contacts", "drive", "file", "photo", "sso", "synologymeet",
+];
+export function isPortalAlias(value) {
+    return typeof value === "string" && PORTAL_ALIAS_PATTERN.test(value) && !RESERVED_PORTAL_ALIASES.includes(value);
+}
+/** The package name as a slug; a reserved or too long name falls back to a stable hash. */
+export function defaultPortalAlias(packageId) {
+    const slug = packageId.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return isPortalAlias(slug) ? slug : `app-${createHash("sha256").update(packageId).digest("hex").slice(0, 12)}`;
+}
+/** `{}` or `{alias}`; undefined for any other shape. */
+export function readPortalDeclaration(value, packageId) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const keys = Object.keys(value);
+    if (keys.some((key) => key !== "alias"))
+        return undefined;
+    const alias = value.alias;
+    if (alias === undefined)
+        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

@@ -0,0 +1,33 @@
+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";
+/** Install wizard key; DSM exports it to preinst/postinst. */
+export declare const PORTAL_INSTALL_KEY = "portal_alias";
+/** Package-owned install draft, never DSM's saved portal configuration. */
+export declare const PORTAL_DRAFT = "portal-install.json";
+export interface PortalPackage {
+    /** The DSM app id the alias opens: an AppInstance or a `.url` entry of ui/config. */
+    appId: string;
+    /** Control Panel display name. */
+    application: string;
+    /** 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;
+/** DSM's CGI location: index.cgi launches the app id nginx passes as REWRITE_APP. */
+export declare function renderPortalMustache(): string;
+export declare function renderPortalWizardItems(t: Translate, alias: string): Array<Record<string, unknown>>;
+export declare function renderPortalWizardStep(t: Translate, alias: string): InstallWizardStep;
+/**
+ * preinst validates the wizard answer, postinst stores it and writes it as the
+ * default alias of the package's own portal.json, postupgrade restores it into
+ * the new payload. Activation stays an administrator's AppPortal set call.
+ */
+export declare function renderPortalLifecycle(name: string, portal: PortalPackage): string;