@synopackageland/cli 0.6.1 → 0.7.1

package/dist/contract/validate.js

@@ -4,9 +4,11 @@ import { contractSpan, makeError } from "../errors.js";
 import { collectInstallParameters, getValuePosition, stringViolations, } from "./load.js";
 import { validateContractSchema } from "./schema-validate.js";
 import { DSM_GROUP_NAME, isWebAccessMode, isWebLaunchMode, readWebIntegration } from "./web-launch.js";
+import { contractPortalSupported, readPortalDeclaration } from "../portal/alias.js";
 import { loadCompose } from "../compose/analyze.js";
 import { collectPosixAllSharesParameters, isPosixAllSharesType, validatePosixAllSharesSources, } from "./posix-all-shares.js";
 import { getErrorCode } from "../error-registry.js";
+import { isDsmAtLeast, PORTAL_MIN_DSM, portalMinDsmMessage } from "../build-spk/dsm-version.js";
 import { FORMAL_PACKAGE_IDENTITY_MAX_LENGTH, PACKAGE_IDENTITY_MAX_LENGTH, } from "../deploy/identity-shared.js";
 /** DSM 7.4 Package Center rejects a longer package identity outright. */
 const DSM_PACKAGE_IDENTITY_MAX = 32;
@@ -53,6 +55,7 @@ export function validateContract(parsed, contractFile) {
     errors.push(...validatePosixAllShares(parsed, contractFile));
     errors.push(...validateWebLaunch(parsed, contractFile));
     errors.push(...validateWebAccess(parsed, contractFile));
+    errors.push(...validateWebPortal(parsed, contractFile));
     return errors;
 }
 function validatePosixAllShares(parsed, contractFile) {
@@ -119,6 +122,33 @@ function validateWebAccess(parsed, contractFile) {
     }
     return [];
 }
+function validateWebPortal(parsed, contractFile) {
+    const { contract, doc } = parsed;
+    const portal = readWebIntegration(contract)?.portal;
+    if (portal === undefined) {
+        return [];
+    }
+    const pos = getValuePosition(doc, ["integration", "web", "portal"]) ?? { line: 1, column: 1 };
+    const at = contractSpan(contractFile, pos.line, pos.column, "integration.web.portal");
+    if (!contractPortalSupported(contract)) {
+        return [
+            makeError("CONTRACT_PORTAL_UNSUPPORTED", at, "Application Portal 只支援以 DSM 視窗開啟、經 DSM 登入閘道的網頁 App。", "請使用 adminport、launch: dsm-window 與非 public 的 access，或移除 integration.web.portal。public App 已有同名的 Web Station 網址。"),
+        ];
+    }
+    if (!readPortalDeclaration(portal, String(contract.package ?? ""))) {
+        return [
+            makeError("CONTRACT_PORTAL_INVALID", at, "integration.web.portal 必須是 {} 或 { alias }，alias 為 1–64 個小寫英數字或 -，且不是 DSM 保留路徑。", "請省略 alias 以使用套件名稱，或改成例如 alias: my-app。"),
+        ];
+    }
+    const osMinVer = contract.os_min_ver;
+    if (typeof osMinVer === "string" && FULL_OS_MIN_VER.test(osMinVer) && !isDsmAtLeast(osMinVer, PORTAL_MIN_DSM)) {
+        return [
+            makeError("CONTRACT_PORTAL_MIN_DSM", at, portalMinDsmMessage(osMinVer, "integration.web.portal"), `請把 os_min_ver 改成 "${PORTAL_MIN_DSM}" 或更新，或移除 integration.web.portal。`),
+        ];
+    }
+    return [];
+}
+const FULL_OS_MIN_VER = /^7\.\d+(\.\d+)?-\d+$/;
 function validateDeveloperString(value, contractFile, path, pos) {
     const errors = [];
     const violations = stringViolations(value);

package/dist/deploy/deploy.d.ts

@@ -1,5 +1,5 @@
 import type { CommandRunner } from "../standalone/build.js";
-import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
+import { type NativeArchFamily } from "../build-spk/dsm-arch.js";
 import type { ProjectRoot } from "../discovery.js";
 import type { NasHost } from "../host/types.js";
 import { resolveDeploySpkVersion } from "./spk-version.js";

package/dist/deploy/deploy.js

@@ -1,4 +1,5 @@
 import { buildSpk } from "../build-spk/generator.js";
+import { CONTAINER_ARCH_FAMILIES, isContainerArchFamily } from "../build-spk/dsm-arch.js";
 import { loadContract } from "../contract/load.js";
 import { usesAuthGateway } from "../contract/web-launch.js";
 import { findUnsupportedInstallTypes } from "../contract/unsupported-types.js";
@@ -174,6 +175,13 @@ export async function deployProject(options) {
             };
         }
     }
+    if (archFamily !== undefined && !isContainerArchFamily(archFamily)) {
+        return {
+            ok: false,
+            code: "CONTAINER_ARCH_UNSUPPORTED",
+            message: `Container Manager App 只支援 ${CONTAINER_ARCH_FAMILIES.join("、")}；DSM 不為 ${archFamily} 提供 Container Manager。`,
+        };
+    }
     const build = await buildSpk({
         project: options.project,
         packageIdentity: identity.packageId,

package/dist/deploy/native-install-values.d.ts

@@ -0,0 +1,17 @@
+import type { StandaloneManifest } from "../standalone/manifest.js";
+export type NativeInstallValuesResult = {
+    ok: true;
+    extraValues: Record<string, string>;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Install wizard values for a native-go/binary deploy. Only an install-selected
+ * delegate asks the wizard for anything; preinst refuses an empty selection on
+ * the first install, so refuse it here before building or uploading.
+ */
+export declare function resolveNativeInstallValues(manifest: StandaloneManifest, provided: Record<string, string>, state: {
+    installed: boolean;
+}): NativeInstallValuesResult;

package/dist/deploy/native-install-values.js

@@ -0,0 +1,32 @@
+const USAGE = "synopkgland deploy --param delegate_share=<shared folder>，或 --param delegate_home=true";
+/** Mirrors the preinst draft check in build-spk/delegate-scope.ts. */
+function validShareName(name) {
+    return (name !== "" && name !== "." && !name.includes("..") &&
+        !/[/\\:"%\x00-\x1f\x7f]/.test(name) &&
+        !/^homes?$/i.test(name) && name.trim() === name && name.length <= 256);
+}
+/**
+ * Install wizard values for a native-go/binary deploy. Only an install-selected
+ * delegate asks the wizard for anything; preinst refuses an empty selection on
+ * the first install, so refuse it here before building or uploading.
+ */
+export function resolveNativeInstallValues(manifest, provided, state) {
+    const fail = (code, message) => ({ ok: false, code, message });
+    const selected = manifest.capabilities.delegate?.scope === "install-selected";
+    const names = Object.keys(provided);
+    if (!selected && names.length)
+        return fail("DEPLOY_PARAM_UNDECLARED", `${manifest.package} has no install wizard values; remove --param ${names[0]}.`);
+    const unknown = names.find((name) => name !== "delegate_share" && name !== "delegate_home");
+    if (unknown)
+        return fail("DEPLOY_PARAM_UNDECLARED", `--param ${unknown} is not an install wizard value. Use: ${USAGE}.`);
+    const { delegate_share: share, delegate_home: home } = provided;
+    if (home !== undefined && home !== "true" && home !== "false")
+        return fail("DEPLOY_PARAM_TYPE_INVALID", "--param delegate_home must be true or false.");
+    if (share !== undefined && !validShareName(share))
+        return fail("DEPLOY_PARAM_TYPE_INVALID", `--param delegate_share must be one Shared Folder name, not a path, home or homes.`);
+    if (share !== undefined && home === "true")
+        return fail("DEPLOY_PARAM_TYPE_INVALID", "Choose either --param delegate_share or --param delegate_home=true, not both.");
+    if (selected && !state.installed && share === undefined && home !== "true")
+        return fail("DEPLOY_PARAM_REQUIRED", `The first install of ${manifest.package} must select the delegate scope: ${USAGE}.`);
+    return { ok: true, extraValues: { ...provided } };
+}

package/dist/deploy/plan.d.ts

@@ -1,8 +1,9 @@
+import { type CommandRunner } from "../standalone/build.js";
 import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
 import type { NasHost } from "../host/types.js";
 export interface DeploymentPlan {
     root: string;
-    kind: "native-go" | "binary" | "container";
+    kind: "native-go" | "binary" | "native-layout" | "container";
     packageId: string;
     version: string;
     arch?: NativeArchFamily;
@@ -15,4 +16,7 @@ export declare function planDeployment(root: string, options?: {
     arch?: NativeArchFamily;
     dev?: boolean;
 }): DeploymentPlan;
-export declare function deployStandalone(plan: DeploymentPlan, host: NasHost): Promise<string>;
+export declare function deployStandalone(plan: DeploymentPlan, host: NasHost, options?: {
+    params?: Record<string, string>;
+    run?: CommandRunner;
+}): Promise<string>;

package/dist/deploy/plan.js

@@ -3,14 +3,18 @@ import { loadContract } from "../contract/load.js";
 import { validateProject } from "../validate.js";
 import { findStandaloneRoot, loadStandaloneManifest, } from "../standalone/manifest.js";
 import { buildStandalone } from "../standalone/build.js";
+import { buildNativeLayout, isNativeLayout, loadNativeLayout } from "../standalone/native-layout.js";
 import { resolveDeployIdentity } from "./identity.js";
 import { nextDeployVersion } from "./spk-version.js";
+import { resolveNativeInstallValues } from "./native-install-values.js";
 function fail(code, message) {
     return Object.assign(new Error(`[${code}] ${message}`), { code });
 }
 /** Purely local planning: no credentials, network, build or installation. */
 export function planDeployment(root, options = {}) {
     const standalone = findStandaloneRoot(root);
+    if (standalone && isNativeLayout(standalone))
+        return planNativeLayout(standalone, options);
     if (standalone) {
         const validation = validateProject(findProjectRoot(standalone));
         if (!validation.ok)
@@ -22,7 +26,7 @@ export function planDeployment(root, options = {}) {
         if (options.dev)
             throw fail("DEVELOPMENT_INSTANCE_UNSUPPORTED", "--dev is not supported for native-go/binary; choose a distinct package name at init");
         if (options.arch && !m.arches.includes(options.arch))
-            throw fail("STANDALONE_ARCH_NOT_DECLARED", `Architecture not declared: ${options.arch}`);
+            throw fail("STANDALONE_ARCH_NOT_DECLARED", `Architecture not declared: ${options.arch}; add it to dsm-package.yaml arches to deploy it`);
         return {
             root: standalone,
             kind: m.backend.kind === "go" ? "native-go" : "binary",
@@ -33,7 +37,7 @@ export function planDeployment(root, options = {}) {
             transport: "dsm-local-spk",
             notes: m.capabilities.rootOps || m.capabilities.delegate
                 ? [
-                    "Installation does not mean ready. Approve boot and control tasks once in the App window; executor or policy digest changes require approval again.",
+                    "Installation does not mean ready. Approve boot and control tasks once in the App window. An executor-only upgrade stays ready without approval (INFO anchors the executor digest); a policy digest change requires approval again.",
                 ]
                 : [],
         };
@@ -59,7 +63,56 @@ export function planDeployment(root, options = {}) {
         ],
     };
 }
-export async function deployStandalone(plan, host) {
+/** DSM reports the aarch64 family; a native layout may name it armv8. */
+function layoutArchFor(arches, family) {
+    const names = family === "aarch64" ? ["aarch64", "armv8"] : [family];
+    return names.find((name) => arches.includes(name));
+}
+function loadLayout(root) {
+    const loaded = loadNativeLayout(root);
+    if (!loaded.ok)
+        throw fail(loaded.errors[0].code, loaded.errors.map((e) => e.message).join("\n"));
+    return loaded.manifest;
+}
+function planNativeLayout(root, options) {
+    const m = loadLayout(root);
+    if (options.dev)
+        throw fail("DEVELOPMENT_INSTANCE_UNSUPPORTED", "--dev is not supported for a native layout; choose a distinct package name");
+    if (options.arch && !layoutArchFor(m.arches, options.arch))
+        throw fail("STANDALONE_ARCH_NOT_DECLARED", `Architecture not declared: ${options.arch}; add it to dsm-package.yaml arches to deploy it`);
+    return {
+        root,
+        kind: "native-layout",
+        packageId: m.package,
+        version: `${m.version}-${String(m.build).padStart(4, "0")}`,
+        arch: options.arch,
+        capabilities: [],
+        transport: "dsm-local-spk",
+        notes: [],
+    };
+}
+async function buildForDeploy(plan, arch, installed, options) {
+    if (plan.kind === "native-layout") {
+        const m = loadLayout(plan.root);
+        const layoutArch = layoutArchFor(m.arches, arch);
+        if (!layoutArch)
+            throw fail("STANDALONE_ARCH_NOT_DECLARED", `Architecture not declared: ${arch}; add it to dsm-package.yaml arches to deploy it`);
+        const name = Object.keys(options.params ?? {})[0];
+        if (name)
+            throw fail("DEPLOY_PARAM_UNDECLARED", `${m.package} has no install wizard values; remove --param ${name}.`);
+        const { outputs } = await buildNativeLayout({ root: plan.root, arches: [layoutArch], run: options.run });
+        return { outputs, extraValues: {} };
+    }
+    const loaded = loadStandaloneManifest(plan.root);
+    if (!loaded.ok)
+        throw fail(loaded.errors[0].code, loaded.errors.map((e) => e.message).join("\n"));
+    const values = resolveNativeInstallValues(loaded.manifest, options.params ?? {}, { installed });
+    if (!values.ok)
+        throw fail(values.code, values.message);
+    const { outputs } = await buildStandalone({ root: plan.root, arches: [arch], run: options.run });
+    return { outputs, extraValues: values.extraValues };
+}
+export async function deployStandalone(plan, host, options = {}) {
     if (plan.kind === "container")
         throw fail("DEPLOY_PLAN_INVALID", "Expected native-go or binary deployment plan");
     const arch = plan.arch ?? (await host.getArchFamily?.());
@@ -70,16 +123,14 @@ export async function deployStandalone(plan, host) {
         nextDeployVersion(plan.version, installed) !== plan.version) {
         throw fail("DEPLOY_VERSION_INVALID", `Increase dsm-package.yaml version/build above installed ${installed}`);
     }
-    const { outputs } = await buildStandalone({
-        root: plan.root,
-        arches: [arch],
-    });
+    const { outputs, extraValues } = await buildForDeploy(plan, arch, Boolean(installed), options);
     if (outputs.length !== 1)
         throw fail("DEPLOY_BUILD_OUTPUT_INVALID", "Expected one SPK");
     await host.installFromLocalSpk({
         packageId: plan.packageId,
         version: plan.version,
         spkPath: outputs[0],
+        extraValues,
     });
     return outputs[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,8 +1,8 @@
 export const ERROR_REGISTRY = {
     "NATIVE_LAYOUT_INVALID": {
         code: "NATIVE_LAYOUT_INVALID",
-        description: "Native layout manifest, hook, toolkit or artifact violates the package-only contract.",
-        suggestion: "Use schema 2 with backend.kind: native; check paths, ELF linkage and checksum pins."
+        description: "native layout 的 manifest、hook、toolkit 或產物違反 package-only 契約。",
+        suggestion: "使用 schema 2 與 backend.kind: native；檢查路徑、ELF 連結與 checksum pin。"
     },
     "COMPOSE_ROUTE_UNSUPPORTED": {
         "code": "COMPOSE_ROUTE_UNSUPPORTED",
@@ -59,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 模式無效。",
@@ -87,12 +97,12 @@ export const ERROR_REGISTRY = {
     "GATEWAY_GO_MISSING": {
         "code": "GATEWAY_GO_MISSING",
         "description": "建置 DSM 驗證閘道需要 Go，但找不到 go 指令。",
-        "suggestion": "請安裝 Go 1.24 以上版本（https://go.dev/dl/），或在 integration.web.access 明確選 public。"
+        "suggestion": "請安裝 Go 1.21 以上版本（https://go.dev/dl/，建置時固定使用 go1.26.9），或在 integration.web.access 明確選 public。"
     },
     "GATEWAY_BUILD_FAILED": {
         "code": "GATEWAY_BUILD_FAILED",
         "description": "DSM 驗證閘道建置失敗或產出不是對應架構的靜態 ELF。",
-        "suggestion": "請查看 go build 輸出；確認 Go 版本 1.24 以上且 templates/_gateway 未被修改。"
+        "suggestion": "請查看 go build 輸出；閘道固定以 go1.26.9 建置，離線時請安裝 go1.26.9 或讓 GOPROXY 可提供 golang.org/toolchain，並確認 templates/_gateway 未被修改。"
     },
     "CONTRACT_INVALID_STRING": {
         "code": "CONTRACT_INVALID_STRING",
@@ -116,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",
@@ -336,8 +346,13 @@ export const ERROR_REGISTRY = {
     },
     "DEPLOY_PARAM_UNDECLARED": {
         "code": "DEPLOY_PARAM_UNDECLARED",
-        "description": "deploy --param 提供了契約未宣告的 Install Parameter。",
-        "suggestion": "請只傳 synology-app.yaml install 中宣告的 string 或 boolean 名稱。"
+        "description": "deploy --param 提供了契約未宣告的 Install Parameter，或 native-go／binary 套件沒有的安裝精靈值。",
+        "suggestion": "Compose 請只傳 synology-app.yaml install 中宣告的 string 或 boolean 名稱；native-go／binary 只接受 install-selected delegate 的 delegate_share 或 delegate_home。"
+    },
+    "DEPLOY_PARAM_REQUIRED": {
+        "code": "DEPLOY_PARAM_REQUIRED",
+        "description": "首次安裝 install-selected delegate 套件時沒有提供安裝精靈的範圍值，preinst 會拒絕安裝。",
+        "suggestion": "加上 --param delegate_share=<共用資料夾> 或 --param delegate_home=true 再部署。"
     },
     "DEPLOY_PARAM_TYPE_INVALID": {
         "code": "DEPLOY_PARAM_TYPE_INVALID",
@@ -402,7 +417,7 @@ export const ERROR_REGISTRY = {
     "STANDALONE_DAEMON_BUILD_FAILED": {
         "code": "STANDALONE_DAEMON_BUILD_FAILED",
         "description": "無法建置套件 daemon 的 Go supervisor。",
-        "suggestion": "安裝 Go 1.24 以上並檢查 compiler stderr；NAS 不需要 Go toolchain。"
+        "suggestion": "安裝 Go 1.21 以上（建置固定使用 go1.26.9，離線時請先備妥）並檢查 compiler stderr；NAS 不需要 Go toolchain。"
     },
     "STANDALONE_DAEMON_PAYLOAD_INVALID": {
         "code": "STANDALONE_DAEMON_PAYLOAD_INVALID",
@@ -472,7 +487,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",
@@ -506,8 +521,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",
@@ -574,6 +589,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 設定不合法。",
@@ -629,6 +649,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。" };
@@ -641,10 +663,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 檔案。" };
@@ -662,10 +683,23 @@ 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 1.21 以上且可取得 go1.26.9（離線時請先備妥），查看訊息中的編譯器輸出；原始碼缺少時重新安裝 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。" };
+ERROR_REGISTRY["DSM_TLS_UNTRUSTED"] = { "code": "DSM_TLS_UNTRUSTED", "description": "DSM 的 TLS 憑證不受這台電腦信任（自簽、過期或名稱不符）。", "suggestion": "把 NAS 憑證或其 CA 匯出成 PEM，用 NODE_EXTRA_CA_CERTS=<該檔> 執行；或讓 DSM 使用與 host profile 名稱相符的受信任憑證。不要關閉憑證驗證。" };

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

@@ -3,6 +3,7 @@ import { listShareNamesWithSynoagentcli, lookupSharePathWithSynoagentcli, } from
 import { createSynoagentcliApiCall, fetchSharePermissions, fetchUserGroups, } from "./share-permission-lookup.js";
 import { fetchPortInfo } from "./port-info-lookup.js";
 import { dsmFetch } from "./dsm-http.js";
+import { versionUnsupported } from "../runtime/dsm-version.js";
 import { fetchDsmPortProfileInventory } from "./dsm-port-profile.js";
 import { installPackageFromLocalSpk, fetchInstalledPackageState, packageStateFromRecord, } from "./catalog-install.js";
 import { resolveHostCredentials } from "./credentials.js";
@@ -53,6 +54,16 @@ export function homesPathFromDsmUserHomeRead(result) {
     }
     return `${volume}/homes`;
 }
+function setCookiePairs(headers) {
+    const lines = typeof headers.getSetCookie === "function"
+        ? headers.getSetCookie()
+        : headers.get("set-cookie")
+            ? [headers.get("set-cookie")]
+            : [];
+    return lines
+        .map((line) => line.split(";")[0]?.trim())
+        .filter((pair) => Boolean(pair));
+}
 function createDsmNasHost(credentials, profileName) {
     const dsmOrigin = credentials.dsmOrigin.replace(/\/$/, "");
     let cookieHeader = credentials.cookieHeader;
@@ -77,15 +88,7 @@ function createDsmNasHost(credentials, profileName) {
         const login = (await response.json());
         if (!response.ok || login.success !== true)
             throw new Error("DSM login failed");
-        const setCookie = typeof response.headers.getSetCookie === "function"
-            ? response.headers.getSetCookie()
-            : response.headers.get("set-cookie")
-                ? [response.headers.get("set-cookie")]
-                : [];
-        const pairs = setCookie
-            .map((line) => line.split(";")[0]?.trim())
-            .filter((pair) => Boolean(pair));
-        cookieHeader = pairs.join("; ");
+        cookieHeader = setCookiePairs(response.headers).join("; ");
         if (!cookieHeader)
             throw new Error("DSM login returned no session cookie");
     };
@@ -106,12 +109,38 @@ function createDsmNasHost(credentials, profileName) {
         async getExecutorStatus(packageIdentity) {
             try {
                 await ensureLogin();
-                const response = await dsmFetch(`${dsmOrigin}/webman/3rdparty/${encodeURIComponent(packageIdentity)}/cgi/api.cgi`, {
-                    method: "POST", headers: { cookie: cookieHeader ?? "", "content-type": "application/json" },
-                    body: JSON.stringify({ method: "executor.status", params: {} }),
-                });
-                const body = await response.json();
-                return body.success ? body.data : undefined;
+                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")
+                    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);
+                }
             }
             catch {
                 return undefined;
@@ -130,6 +159,12 @@ function createDsmNasHost(credentials, profileName) {
                         throw Object.assign(new Error(`DSM ${body.error?.code ?? "error"}: scheduler readback denied; check the administrator session. No retry was made.`), { code: body.error?.code });
                     return body.data;
                 };
+                // DSM 7.1 stops at TaskScheduler list v2 (offset) and get v3; only an unsupported version falls back.
+                const taskRead = (method, version, params, legacyVersion, legacyParams) => call("SYNO.Core.TaskScheduler", method, version, params).catch((e) => {
+                    if (!versionUnsupported(e.code))
+                        throw e;
+                    return call("SYNO.Core.TaskScheduler", method, legacyVersion, legacyParams);
+                });
                 const records = await call("SYNO.Core.EventScheduler", "list", 1, {});
                 if (!Array.isArray(records))
                     throw new Error("Invalid EventScheduler readback.");
@@ -142,13 +177,14 @@ function createDsmNasHost(credentials, profileName) {
                         throw new Error("Invalid boot task readback.");
                     tasks.push({ ...detail, name: detail.task_name, kind: "boot" });
                 }
-                const listed = await call("SYNO.Core.TaskScheduler", "list", 3, { start: 0, limit: 500 });
+                const listed = await taskRead("list", 3, { start: 0, limit: 500 }, 2, { offset: 0, limit: 500 });
                 if (!Array.isArray(listed?.tasks) || !Number.isInteger(listed.total) || listed.total !== listed.tasks.length || listed.total > 500)
                     throw new Error("Incomplete TaskScheduler readback.");
                 for (const summary of listed.tasks) {
                     if (summary?.name !== `${packageIdentity} executor control`)
                         continue;
-                    const detail = await call("SYNO.Core.TaskScheduler", "get", 4, { id: summary.id, real_owner: summary.real_owner });
+                    const ref = { id: summary.id, real_owner: summary.real_owner };
+                    const detail = await taskRead("get", 4, ref, 3, ref);
                     if (!detail || String(detail.id) !== String(summary.id) || detail.name !== summary.name)
                         throw new Error("Invalid control task readback.");
                     tasks.push({ ...detail, kind: "control" });
@@ -275,17 +311,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;
 }