@synopackageland/cli 0.7.0 → 0.7.2

package/dist/cli.js

@@ -1,8 +1,9 @@
 import { Command, CommanderError } from "commander";
-import { readFileSync, renameSync } from "node:fs";
+import { existsSync, readFileSync, renameSync } from "node:fs";
 import { resolve, dirname, join } from "node:path";
 import { findProjectRoot } from "./discovery.js";
 import { loadContract } from "./contract/load.js";
+import { contractIconPath } from "./contract/icon.js";
 import { formatErrors } from "./errors.js";
 import { formatInspectReport, inspectProject } from "./inspect.js";
 import { formatPinReport, pinProjectImages } from "./images/pin.js";
@@ -16,6 +17,7 @@ import { testProject } from "./test-command.js";
 import { buildSpk } from "./build-spk/generator.js";
 import { CONTAINER_ARCH_FAMILIES, isContainerArchFamily, isNativeArchFamily, NATIVE_ARCH_FAMILIES, parseArchList, } from "./build-spk/dsm-arch.js";
 import { DEFAULT_MIN_DSM, CONTAINER_MIN_DSM } from "./build-spk/dsm-version.js";
+import { iconReport } from "./build-spk/dsm-icons.js";
 import { deployProject } from "./deploy/deploy.js";
 import { planDeployment, deployStandalone } from "./deploy/plan.js";
 import { createNasHost } from "./host/dsm-client.js";
@@ -48,6 +50,17 @@ function collectKv(value, previous, flag) {
         [value.slice(0, separator)]: value.slice(separator + 1),
     };
 }
+/** check's icon lines (stdout) and its single-colour warning (stderr). */
+function formatIconReport(report, manifestFile) {
+    return {
+        lines: report.source === "custom"
+            ? [`圖示：自訂 ${report.path}`]
+            : report.source === "layout"
+                ? ["圖示：由 layout metadata 的 PACKAGE_ICON*.PNG 提供（若有）", `info：在 ${manifestFile} 設定 icon: 可改由 CLI 產生 Package Center 圖示。`]
+                : ["圖示：SDK 預設圖示", `info：在 ${manifestFile} 設定 icon: <正方形 PNG（至少 256×256）或 icon_<size>.png 目錄> 換成自己的圖示。`],
+        ...(report.solid ? { warning: "warning：圖示只有單一顏色，Package Center 與 DSM 主選單會像一個色塊；建議換成有圖形的圖示。" } : {}),
+    };
+}
 function formatSpkInspection(spk, report) {
     return [
         `SPK：${spk}`,
@@ -55,6 +68,7 @@ function formatSpkInspection(spk, report) {
         `arch：${report.arch ?? "?"}  runtime：${report.kind ?? "?"}`,
         `簽署：${report.signed ? "有 Synology 簽章" : "未簽署（Package Center 需允許任何發行者）"}`,
         `CGI：${report.cgi ?? "無"}`,
+        ...(report.icon ? [`圖示：${report.icon.source === "default" ? "SDK 預設圖示" : report.icon.source === "custom" ? `自訂（PACKAGE_ICON_256 sha256 ${report.icon.sha256.slice(0, 12)}…）` : "無 PACKAGE_ICON"}`] : []),
         ...(report.entry === "admin-only" ? ["入口：entry: admin-only，只有 DSM 管理員能開啟與呼叫任何 route（含 SDK routes）"] : []),
         ...(report.entry === "app-privilege" ? ["入口：entry: app-privilege，由 DSM 控制台「應用程式權限」決定誰能使用"] : []),
         ...(report.portal ? [`Application Portal：預設別名 /${report.portal.alias}/（${report.portal.appId}），由管理員套用後啟用`] : []),
@@ -62,7 +76,11 @@ function formatSpkInspection(spk, report) {
         "payload：",
         ...(report.uninstallCleanup ?? []).map(item => `Uninstall cleanup (if needed)：${item.target} — ${item.condition} ${item.action}`),
         ...report.payload.map((e) => `  ${e.mode} ${e.path}`),
-        report.findings.length ? "問題：" : "檢查：沒有 root 權限需求或異常。",
+        report.findings.length
+            ? "問題："
+            : report.executor
+                ? "檢查：沒有異常。管理員核准後會建立 root executor 排程（boot 與 control task），以 root 執行此 SPK 固定的 executor 與 policy。"
+                : "檢查：沒有 root 權限需求或異常。",
         ...report.findings.map((f) => `  - ${f}`),
     ].join("\n");
 }
@@ -149,10 +167,16 @@ export async function runCli(argv) {
             const loaded = isNativeLayout(standalone) ? loadNativeLayout(standalone) : loadStandaloneManifest(standalone);
             if (!loaded.ok)
                 throw failure(loaded.errors[0].code, loaded.errors.map((e) => `[${e.code}] ${e.message}`).join("\n"), "將 dsm-package.yaml 更新為 schema: 2，修正宣告後重試。");
+            const declared = "icon" in loaded.manifest && loaded.manifest.icon ? resolve(standalone, loaded.manifest.icon) : undefined;
+            const icon = isNativeLayout(standalone) && !declared ? { source: "layout", solid: false } : iconReport(standalone, declared);
+            const iconText = formatIconReport(icon, "dsm-package.yaml");
+            if (iconText.warning)
+                console.error(iconText.warning);
             emit("check", {
                 package: loaded.manifest.package,
                 capabilities: "capabilities" in loaded.manifest ? loaded.manifest.capabilities : {},
-            }, "驗證通過。");
+                icon,
+            }, ["驗證通過。", ...iconText.lines].join("\n"));
             return;
         }
         const project = requireProject(rootOf(command));
@@ -162,7 +186,11 @@ export async function runCli(argv) {
         if (!result.ok)
             throw failure(result.errors[0].code, formatErrors(result.errors), result.errors[0].suggestion);
         const report = inspectProject(project);
-        emit("check", { report, warnings: result.warnings ?? [] }, `驗證通過。\n${formatInspectReport(report)}`);
+        const icon = iconReport(project.root, contractIconPath(loadContract(project.contractPath).contract, project.root));
+        const iconText = formatIconReport(icon, "synology-app.yaml");
+        if (iconText.warning)
+            console.error(iconText.warning);
+        emit("check", { report, warnings: result.warnings ?? [], icon }, [`驗證通過。`, formatInspectReport(report), ...iconText.lines].join("\n"));
     });
     program
         .command("inspect <spk>")
@@ -234,13 +262,15 @@ export async function runCli(argv) {
         });
         stdout(`已建立 ${options.template} 專案於 ${targetDir}`);
         if (options.template === "native-go")
-            stdout(`下一步：\n  cd ${dir}\n  (cd backend && go test ./...)\n  synopkgland build\n說明見 README.md。`);
+            stdout(`下一步：\n  cd ${dir}\n  (cd backend && go test ./...)\n${existsSync(join(targetDir, "frontend", "package.json")) ? "  (cd frontend && npm ci)\n" : ""}  synopkgland build\n說明見 README.md。`);
     });
     program
         .command("add <caps...>")
         .description(`加入能力（${CAPABILITY_NAMES.join("、")}）或 portal 與 SDK-owned overlay；不覆寫既有應用檔案`)
         .action((caps, _options, command) => {
         const result = addCapabilities(rootOf(command), caps);
+        for (const note of result.notes ?? [])
+            console.error(`[注意] ${note}`);
         stdout(`已新增：${result.added.join(", ") || "無"}；已存在：${result.unchanged.join(", ") || "無"}`);
     });
     program
@@ -281,7 +311,7 @@ export async function runCli(argv) {
         .option("--dev", "Development Package Identity")
         .option("--share <slot=name>", "Compose 共用資料夾", (value, previous) => collectKv(value, previous, "--share"))
         .option("--run-as <slot=name>", "Compose DSM 使用者", (value, previous) => collectKv(value, previous, "--run-as"))
-        .option("--param <NAME=value>", "Compose 安裝參數", (value, previous) => collectKv(value, previous, "--param"))
+        .option("--param <NAME=value>", "安裝參數（Compose）或安裝精靈值（native-go／binary）", (value, previous) => collectKv(value, previous, "--param"))
         .option("--dry-run", "只輸出本機部署計畫，不連接 NAS")
         .action(async (options, command) => {
         if (options.arch !== undefined &&
@@ -292,15 +322,15 @@ export async function runCli(argv) {
             dev: options.dev,
         });
         if (plan.kind !== "container" &&
-            (options.share || options.runAs || options.param))
-            throw failure("CLI_OPTION_INVALID", "native-go／binary 不接受 Compose 安裝參數。");
+            (options.share || options.runAs))
+            throw failure("CLI_OPTION_INVALID", "native-go／binary 不接受 --share／--run-as；安裝精靈值請用 --param。");
         if (options.dryRun) {
             emit("deploy", plan, JSON.stringify(plan, null, 2));
             return;
         }
         if (plan.kind !== "container") {
             const host = hostOf(options.host);
-            const output = await deployStandalone(plan, host);
+            const output = await deployStandalone(plan, host, { params: options.param });
             const status = await standaloneInfo({ root: plan.root, host });
             emit("deploy", { ...plan, output, status }, `已部署 ${plan.packageId}: ${output}\n${formatProjectInfo(status)}${plan.notes.length ? "\n" + plan.notes.join("\n") : ""}`);
             return;

package/dist/contract/i18n.d.ts

@@ -0,0 +1,5 @@
+import type { AppContract, ValidationError } from "../types.js";
+import { type ParsedContract } from "./load.js";
+import type { AppTitle } from "../build-spk/ui-texts.js";
+export declare function contractAppTitle(contract: AppContract): AppTitle;
+export declare function validateContractI18n(parsed: ParsedContract, contractFile: string): ValidationError[];

package/dist/contract/i18n.js

@@ -0,0 +1,45 @@
+import { contractSpan, makeError } from "../errors.js";
+import { getValuePosition } from "./load.js";
+import { readInfoTranslations } from "../standalone/i18n.js";
+/** Same rule as dsm-package.yaml text: INFO and DSM strings files quote with " and cannot escape. */
+function plain(value) {
+    return typeof value === "string" && value.trim() !== "" && !/[\r\n"\\]/.test(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** `i18n.info` as validation accepted it; undefined when absent or invalid. */
+function contractInfo(contract) {
+    if (!isRecord(contract.i18n))
+        return undefined;
+    return readInfoTranslations(contract.i18n.info, { invalid: () => undefined, text: (value) => (plain(value) ? value : undefined) });
+}
+export function contractAppTitle(contract) {
+    return {
+        displayname: String(contract.displayname ?? contract.package),
+        description: String(contract.description ?? ""),
+        info: contractInfo(contract),
+    };
+}
+export function validateContractI18n(parsed, contractFile) {
+    const { contract, doc } = parsed;
+    if (contract.i18n === undefined)
+        return [];
+    const errors = [];
+    const invalid = (why) => {
+        const pos = getValuePosition(doc, ["i18n"]) ?? { line: 1, column: 1 };
+        errors.push(makeError("CONTRACT_I18N_INVALID", contractSpan(contractFile, pos.line, pos.column, "i18n"), `i18n ${why}`, "i18n 只接受 info；info 以 zh-TW、ja 等支援語言為 key，值為單行、不含 \" 或 \\ 的 displayname / description（英文寫在頂層）。"));
+        return undefined;
+    };
+    const text = (value, field) => plain(value) ? value : invalid(`${field} 必須是單行、非空且不含 " 或 \\ 的文字。`);
+    if (!isRecord(contract.i18n) || Object.keys(contract.i18n).some((key) => key !== "info")) {
+        return invalid("只接受 info（各語言的 displayname 與 description）。") ?? errors;
+    }
+    const info = readInfoTranslations(contract.i18n.info, { invalid: (why) => invalid(`.info ${why}`), text });
+    if (info && Object.keys(info).length > 0) {
+        // DSM resolves the window title from ui/texts strings, which carry the English text too.
+        text(contract.displayname, "displayname");
+        text(contract.description, "description");
+    }
+    return errors;
+}

package/dist/contract/icon.d.ts

@@ -0,0 +1,5 @@
+import type { AppContract, ValidationError } from "../types.js";
+import { type ParsedContract } from "./load.js";
+/** `icon` resolved against the project root; validation keeps it inside the project. */
+export declare function contractIconPath(contract: AppContract, root: string): string | undefined;
+export declare function validateContractIcon(parsed: ParsedContract, contractFile: string): ValidationError[];

package/dist/contract/icon.js

@@ -0,0 +1,27 @@
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { contractSpan, makeError } from "../errors.js";
+import { getValuePosition } from "./load.js";
+import { renderPackageIcons } from "../build-spk/dsm-icons.js";
+/** `icon` resolved against the project root; validation keeps it inside the project. */
+export function contractIconPath(contract, root) {
+    return typeof contract.icon === "string" ? resolve(root, contract.icon) : undefined;
+}
+export function validateContractIcon(parsed, contractFile) {
+    const { contract, doc, contractPath } = parsed;
+    if (contract.icon === undefined || !contractPath)
+        return [];
+    const pos = getValuePosition(doc, ["icon"]) ?? { line: 1, column: 1 };
+    const invalid = (message) => [makeError("CONTRACT_ICON_INVALID", contractSpan(contractFile, pos.line, pos.column, "icon"), `icon：${message}`, "icon 填專案內的正方形 PNG（至少 256×256），或含 icon_256.png 的 icon_<size>.png 目錄；省略則使用 SDK 預設圖示。")];
+    const root = dirname(contractPath);
+    const rel = typeof contract.icon === "string" && contract.icon.trim() !== "" ? relative(root, resolve(root, contract.icon)) : undefined;
+    if (rel === undefined || isAbsolute(String(contract.icon)) || rel.startsWith("..") || isAbsolute(rel)) {
+        return invalid(`「${String(contract.icon)}」必須是位於專案目錄內的相對路徑。`);
+    }
+    try {
+        renderPackageIcons(resolve(root, rel));
+        return [];
+    }
+    catch (error) {
+        return invalid(error.message);
+    }
+}

package/dist/contract/validate.js

@@ -5,6 +5,8 @@ import { collectInstallParameters, getValuePosition, stringViolations, } from ".
 import { validateContractSchema } from "./schema-validate.js";
 import { DSM_GROUP_NAME, isWebAccessMode, isWebLaunchMode, readWebIntegration } from "./web-launch.js";
 import { contractPortalSupported, readPortalDeclaration } from "../portal/alias.js";
+import { validateContractIcon } from "./icon.js";
+import { validateContractI18n } from "./i18n.js";
 import { loadCompose } from "../compose/analyze.js";
 import { collectPosixAllSharesParameters, isPosixAllSharesType, validatePosixAllSharesSources, } from "./posix-all-shares.js";
 import { getErrorCode } from "../error-registry.js";
@@ -56,6 +58,8 @@ export function validateContract(parsed, contractFile) {
     errors.push(...validateWebLaunch(parsed, contractFile));
     errors.push(...validateWebAccess(parsed, contractFile));
     errors.push(...validateWebPortal(parsed, contractFile));
+    errors.push(...validateContractIcon(parsed, contractFile));
+    errors.push(...validateContractI18n(parsed, contractFile));
     return errors;
 }
 function validatePosixAllShares(parsed, contractFile) {

package/dist/contract/web-launch.js

@@ -1,4 +1,6 @@
 import { createHash } from "node:crypto";
+import { uiTitleFields } from "../build-spk/ui-texts.js";
+import { contractAppTitle } from "./i18n.js";
 /** DSM Web Station portal alias max length (error 1311 above this). */
 export const WEB_STATION_ALIAS_MAX = 20;
 export const WEB_LAUNCH_MODES = ["dsm-window", "new-page"];
@@ -139,13 +141,15 @@ export function renderWebStationResource(contract) {
 }
 export function renderDsmWindowConfig(contract) {
     const packageId = String(contract.package);
+    const { title, desc, preloadTexts } = uiTitleFields(contractAppTitle(contract));
     return `${JSON.stringify({
         ".url": {
             [packageId]: {
                 type: "url",
                 allUsers: true,
-                title: String(contract.displayname ?? packageId),
-                desc: String(contract.description ?? ""),
+                title,
+                desc,
+                ...(preloadTexts ? { preloadTexts } : {}),
                 icon: "images/app_{0}.png",
                 url: trustedAppEntryPath(contract),
             },

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)
@@ -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/error-registry.js

@@ -97,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",
@@ -346,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",
@@ -412,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",
@@ -685,7 +690,7 @@ export function getErrorCode(code) {
     return ERROR_REGISTRY[code];
 }
 for (const [code, description, suggestion] of [
-    ["EXECUTOR_BUILD_FAILED", "executor 或 lifecycle helper 編譯失敗，或 CLI 套件缺少 executor 原始碼。", "確認已安裝 Go，查看訊息中的編譯器輸出；原始碼缺少時重新安裝 CLI。"],
+    ["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 字）。"],
@@ -697,3 +702,7 @@ for (const [code, description, suggestion] of [
 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 名稱相符的受信任憑證。不要關閉憑證驗證。" };
+ERROR_REGISTRY["STANDALONE_ICON_INVALID"] = { "code": "STANDALONE_ICON_INVALID", "description": "dsm-package.yaml 的 icon 不是可用的套件圖示。", "suggestion": "icon 填專案內的正方形 PNG（至少 256×256），或含 icon_256.png 的 icon_<size>.png 目錄；省略則使用 SDK 預設圖示。" };
+ERROR_REGISTRY["CONTRACT_ICON_INVALID"] = { "code": "CONTRACT_ICON_INVALID", "description": "synology-app.yaml 的 icon 不是可用的套件圖示。", "suggestion": "icon 填專案內的正方形 PNG（至少 256×256），或含 icon_256.png 的 icon_<size>.png 目錄；省略則使用 SDK 預設圖示。" };
+ERROR_REGISTRY["CONTRACT_I18N_INVALID"] = { "code": "CONTRACT_I18N_INVALID", "description": "synology-app.yaml 的 i18n 設定不合法。", "suggestion": "i18n 只接受 info；info 以 zh-TW、ja 等支援語言為 key，值為單行、不含 \" 或 \\ 的 displayname / description（英文寫在頂層）。" };

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