@synopackageland/cli 0.7.1 → 0.7.2

package/dist/build-spk/ui-texts.js

@@ -0,0 +1,42 @@
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { DSM_LANGS, LOCALES } from "../standalone/i18n.js";
+const SECTION = "synopkgland";
+const TITLE = `${SECTION}:app_title`;
+const DESC = `${SECTION}:app_desc`;
+function translated(app) {
+    return Object.values(app.info ?? {}).some((text) => text?.displayname || text?.description);
+}
+/**
+ * `ui/config` title fields. With translations they are `section:key`
+ * references DSM resolves from `ui/texts/<lang>/strings` for the main menu
+ * and the window title; without, the literal English text as before.
+ */
+export function uiTitleFields(app) {
+    return translated(app)
+        ? { title: TITLE, desc: DESC, preloadTexts: [TITLE, DESC] }
+        : { title: app.displayname, desc: app.description };
+}
+/** `ui/texts/<dsm lang>/strings` for English and every translated language; none without translations. */
+export function renderUiTexts(app) {
+    const files = new Map();
+    if (!translated(app))
+        return files;
+    for (const locale of LOCALES) {
+        const text = locale === "en" ? undefined : app.info?.[locale];
+        if (locale !== "en" && !text)
+            continue;
+        const title = text?.displayname ?? app.displayname;
+        const desc = text?.description ?? app.description;
+        files.set(DSM_LANGS[locale], `[${SECTION}]\napp_title="${title}"\napp_desc="${desc}"\n`);
+    }
+    return files;
+}
+export function writeUiTexts(uiRoot, app) {
+    for (const [lang, strings] of renderUiTexts(app)) {
+        mkdirSync(join(uiRoot, "texts", lang), { recursive: true });
+        const path = join(uiRoot, "texts", lang, "strings");
+        writeFileSync(path, strings, "utf8");
+        chmodSync(path, 0o644);
+    }
+}

package/dist/cli.js

@@ -3,6 +3,7 @@ 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}），由管理員套用後啟用`] : []),
@@ -153,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));
@@ -166,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>")

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

@@ -703,3 +703,6 @@ ERROR_REGISTRY["STANDALONE_ENTRY_INVALID"] = { "code": "STANDALONE_ENTRY_INVALID
 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/standalone/dsm-window.d.ts

@@ -1,4 +1,5 @@
 import type { EntryMode, StandaloneManifest } from "./manifest.js";
+import { type AppTitle } from "../build-spk/ui-texts.js";
 /** Same path the generated wrapper POSTs to, and the payload location of the CGI. */
 export declare const CGI_PAYLOAD_PATH = "ui/cgi/api.cgi";
 export declare function cgiUrl(packageId: string): string;
@@ -16,6 +17,7 @@ export declare const I18N_RUNTIME: string;
 export declare function windowScriptName(manifest: Pick<StandaloneManifest, "build">): string;
 /** The launcher fields an entry mode fixes; inspect checks a built SPK against them. */
 export declare function entryLauncherAccess(entry: EntryMode): Record<string, unknown>;
+export declare function appTitle(manifest: StandaloneManifest): AppTitle;
 /** `ui/config`: registers the DSM main-menu app and its window class. */
 export declare function renderUiConfig(manifest: StandaloneManifest): string;
 /**

package/dist/standalone/dsm-window.js

@@ -4,6 +4,7 @@ import { PASSWORD_CONFIRM, ROOT_PANEL, ROOT_RUNTIME, rootTasks } from "./root-wi
 import { HOST_ADAPTER_RUNTIME } from "./host-adapter.js";
 import { permitsOrdinaryUsers } from "./api-permissions.js";
 import { PORTAL_RUNTIME } from "./portal-window.js";
+import { uiTitleFields } from "../build-spk/ui-texts.js";
 /** Same path the generated wrapper POSTs to, and the payload location of the CGI. */
 export const CGI_PAYLOAD_PATH = "ui/cgi/api.cgi";
 export function cgiUrl(packageId) {
@@ -62,15 +63,20 @@ export function entryLauncherAccess(entry) {
         ? { allUsers: false }
         : { allUsers: true, grantPrivilege: "all", advanceGrantPrivilege: true };
 }
+export function appTitle(manifest) {
+    return { displayname: manifest.displayname, description: manifest.description, info: manifest.i18n?.info };
+}
 /** `ui/config`: registers the DSM main-menu app and its window class. */
 export function renderUiConfig(manifest) {
     const ns = `SYNO.SDS.${manifest.package}`;
+    const { title, desc, preloadTexts } = uiTitleFields(appTitle(manifest));
     return `${JSON.stringify({
         [windowScriptName(manifest)]: {
             [`${ns}.Instance`]: {
                 type: "app",
-                title: manifest.displayname,
-                desc: manifest.description,
+                title,
+                desc,
+                ...(preloadTexts ? { preloadTexts } : {}),
                 icon: "images/app_{0}.png",
                 appWindow: `${ns}.MainWindow`,
                 allowMultiInstance: false,
@@ -79,7 +85,7 @@ export function renderUiConfig(manifest) {
             },
             [`${ns}.MainWindow`]: {
                 type: "lib",
-                title: manifest.displayname,
+                title,
                 icon: "images/app_{0}.png",
                 depend: [],
             },
@@ -300,6 +306,14 @@ const ROOT_PANEL_CSS = [
     ".dsmapp-rootpanel-primary{background:#057feb;color:#fff;border:1px solid #057feb;border-radius:3px}",
     ".dsmapp-rootpanel-message{color:#c0392b}.dsmapp-rootpanel-hint{color:#526070;font-size:12px}",
 ].join("");
+/**
+ * An install-selected delegate scope is approved only in the app's settings: the
+ * approval carries the scope the administrator picks there, and the window panel
+ * has no scope picker.
+ */
+function settingsOnlyApproval(manifest) {
+    return manifest.ui.build !== undefined && manifest.capabilities.delegate?.scope === "install-selected";
+}
 /**
  * The capabilities.rootOps: true additions to the window: the exact tasks and panel
  * text, the access runtime wired to DSM's own password confirmation and the
@@ -337,10 +351,10 @@ ${PASSWORD_CONFIRM}
       call: ${ns}.call,
       wait: function (ms) { return new Promise(function (resolve) { setTimeout(resolve, ms); }); }
     });
-    var panels = me.body && me.body.dom.querySelector(".dsmapp-rootpanels");
-    if (panels && ${manifest.ui.build !== undefined && manifest.capabilities.delegate?.scope === "install-selected" ? "false" : "true"}) {
+${settingsOnlyApproval(manifest) ? "" : `    var panels = me.body && me.body.dom.querySelector(".dsmapp-rootpanels");
+    if (panels) {
       ${ns}.mountRootPanel(panels, access, null, ${ns}.rootTasks, session().admin);
     }
-`,
+`}`,
     };
 }

package/dist/standalone/i18n.d.ts

@@ -18,6 +18,18 @@ export type CatalogsResult = {
     ok: false;
     errors: StandaloneError[];
 };
+export interface InfoText {
+    displayname?: string;
+    description?: string;
+}
+/** INFO `displayname_<dsm lang>` / `description_<dsm lang>`; English stays top level. */
+export type InfoTranslations = Partial<Record<Locale, InfoText>>;
+export interface InfoTextChecks {
+    invalid(why: string): undefined;
+    /** The plain single-line text INFO and DSM strings files can carry, or undefined after reporting. */
+    text(value: unknown, field: string): string | undefined;
+}
+export declare function readInfoTranslations(value: unknown, check: InfoTextChecks): InfoTranslations | undefined;
 export declare function isLocale(value: string): value is Locale;
 /** `<dir>/<locale>.json` for each shipped locale; en.json is required. */
 export declare function loadCatalogs(dir: string): CatalogsResult;

package/dist/standalone/i18n.js

@@ -17,6 +17,36 @@ export const DSM_LANGS = {
     es: "spn",
     it: "ita",
 };
+const INFO_TEXT_FIELDS = new Set(["displayname", "description"]);
+export function readInfoTranslations(value, check) {
+    if (value === undefined) {
+        return {};
+    }
+    if (!isRecord(value)) {
+        return check.invalid("必須以語言為 key，例如 zh-TW: { displayname, description }。");
+    }
+    const info = {};
+    for (const [locale, text] of Object.entries(value)) {
+        if (!isLocale(locale) || locale === "en") {
+            return check.invalid(`的「${locale}」不是支援的翻譯語言；英文寫在頂層 displayname / description。`);
+        }
+        if (!isRecord(text) || Object.keys(text).some((key) => !INFO_TEXT_FIELDS.has(key))) {
+            return check.invalid(`.${locale} 只接受 displayname 與 description。`);
+        }
+        const entry = {};
+        for (const field of INFO_TEXT_FIELDS) {
+            if (text[field] !== undefined) {
+                const checked = check.text(text[field], `i18n.info.${locale}.${field}`);
+                if (!checked) {
+                    return undefined;
+                }
+                entry[field] = checked;
+            }
+        }
+        info[locale] = entry;
+    }
+    return info;
+}
 const MESSAGE_KEY = /^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)*$/;
 export function isLocale(value) {
     return LOCALES.includes(value);

package/dist/standalone/inspect-spk.d.ts

@@ -30,6 +30,11 @@ export interface SpkInspection {
     };
     /** Declared `entry` mode; `admin-only` is the administrator floor of every route. */
     entry?: EntryMode;
+    /** PACKAGE_ICON_256.PNG: the SDK default, a custom icon (by digest) or none. */
+    icon?: {
+        source: "default" | "custom" | "none";
+        sha256?: string;
+    };
 }
 /** Reads an SPK without installing it and reports how it would run on DSM. */
 export declare function inspectStandaloneSpk(spkPath: string): Promise<SpkInspection>;

package/dist/standalone/inspect-spk.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { inspectNativeLayout } from "./native-layout.js";
 import { inspectExecutor, inspectExecutorAnchor } from "../runtime/executor-inspect.js";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
@@ -20,6 +21,8 @@ import { listPortExposures, loadCompose } from "../compose/analyze.js";
 import { uninstallCleanup } from "../runtime/uninstall-cleanup.js";
 import { PORTAL_JSON_RELPATH, PORTAL_MUSTACHE_RELPATH, portalResource, renderPortalJson, renderPortalLifecycle, renderPortalMustache, renderPortalWizardStep } from "../portal/package.js";
 import { isPortalAlias } from "../portal/alias.js";
+import { defaultPackageIcons, MAX_ICON_BYTES } from "../build-spk/dsm-icons.js";
+import { decodePng } from "../build-spk/png.js";
 const ROOT_SCRIPT_HINTS = [/\bsudo\b/, /\bchown\s+(-\w+\s+)*root\b/, /chmod\s+[ugo]*\+s\b/, /chmod\s+[2467][0-7]{3}\b/];
 /** Reads an SPK without installing it and reports how it would run on DSM. */
 export async function inspectStandaloneSpk(spkPath) {
@@ -41,8 +44,9 @@ export async function inspectSpk(spkPath, expectedKind) {
             for (const key of ["package", "version", "arch", "os_min_ver", "checksum"])
                 if (!info[key])
                     findings.push(`Missing INFO ${key}`);
+            const icon = inspectPackageIcons(dir, findings);
             return { kind: "native-layout", package: info.package, version: info.version, arch: info.arch,
-                signed: existsSync(join(dir, "syno_signature.asc")), payload, findings, capabilities: [] };
+                signed: existsSync(join(dir, "syno_signature.asc")), payload, findings, capabilities: [], icon };
         }
         const payload = await listPayload(join(dir, "package.tgz"), findings);
         const paths = new Set(payload.map(entry => entry.path));
@@ -112,6 +116,7 @@ export async function inspectSpk(spkPath, expectedKind) {
             await checkEntryLauncher(dir, info.package, metadata.entry, findings);
         if (standalone)
             checkSharedFolder(dir, findings, info.package, sharedFolder, executor?.policy.scope === 'install-selected', portal);
+        const icon = inspectPackageIcons(dir, findings);
         const cgiEntry = payload.find((entry) => entry.path === CGI_PAYLOAD_PATH);
         if (standalone && !cgiEntry) {
             findings.push(`payload 沒有 ${CGI_PAYLOAD_PATH}`);
@@ -121,6 +126,7 @@ export async function inspectSpk(spkPath, expectedKind) {
         }
         return {
             kind,
+            icon,
             ...(executor ? { executor } : {}),
             ...(portal ? { portal: { appId: portal.appId, alias: portal.alias } } : {}),
             ...(metadata.entry ? { entry: metadata.entry } : {}),
@@ -156,6 +162,35 @@ async function checkEntryLauncher(dir, pkg, entry, findings) {
         findings.push(`ENTRY_LAUNCHER_MISMATCH sdk-package.json 宣告 entry: ${entry}，但 ui/config 的 launcher 不是 ${JSON.stringify(expected)}；請用 synopkgland build 重新產生`);
     }
 }
+/** Package Center shows PACKAGE_ICON at 64 and 256 px; the package source refuses a release whose icon is over 256 KiB. */
+function inspectPackageIcons(dir, findings) {
+    for (const [name, size] of [["PACKAGE_ICON.PNG", 64], ["PACKAGE_ICON_256.PNG", 256]]) {
+        const bytes = readOptionalBytes(join(dir, name));
+        if (!bytes)
+            continue;
+        if (bytes.length > MAX_ICON_BYTES) {
+            findings.push(`${name} 有 ${bytes.length} bytes，超過 package source 的 256 KiB 上限；上架後整個版本會被拒收`);
+            continue;
+        }
+        try {
+            const image = decodePng(bytes);
+            if (image.width !== size || image.height !== size)
+                findings.push(`${name} 是 ${image.width}×${image.height}，Package Center 需要 ${size}×${size}`);
+        }
+        catch (error) {
+            findings.push(`${name}：${error.message}`);
+        }
+    }
+    const big = readOptionalBytes(join(dir, "PACKAGE_ICON_256.PNG"));
+    if (!big)
+        return { source: "none" };
+    return big.equals(defaultPackageIcons().packageIcon256)
+        ? { source: "default" }
+        : { source: "custom", sha256: createHash("sha256").update(big).digest("hex") };
+}
+function readOptionalBytes(path) {
+    return existsSync(path) ? readFileSync(path) : undefined;
+}
 const OS_MIN_VER = /^7\.\d+(\.\d+)?-\d+$/;
 /** INFO os_min_ver and arch must be values DSM accepts, and arch must match the shipped CGI. */
 async function checkArch(dir, info, kind, hasCgi, findings) {

package/dist/standalone/manifest.d.ts

@@ -2,7 +2,8 @@ import { type PackageMetadata } from "../package-metadata.js";
 import { type DelegateCapability } from "../runtime/executor-policy.js";
 import type { ExecutorPins } from "../runtime/executor-tasks.js";
 import { type NativeArchFamily } from "../build-spk/dsm-arch.js";
-import { type Catalogs, type Locale } from "./i18n.js";
+import { type Catalogs, type InfoTranslations } from "./i18n.js";
+export type { InfoText } from "./i18n.js";
 import { type RootOp } from "./root-ops.js";
 import { type Daemon } from "./daemon.js";
 import { type Background } from "./background.js";
@@ -22,15 +23,11 @@ export type StandaloneBackend = {
     kind: "binary";
     files: Partial<Record<NativeArchFamily, string>>;
 };
-export interface InfoText {
-    displayname?: string;
-    description?: string;
-}
 export interface StandaloneI18n {
     /** UI messages per locale, embedded into the DSM window. */
     catalogs?: Catalogs;
     /** INFO `displayname_<dsm lang>` / `description_<dsm lang>`. */
-    info: Partial<Record<Locale, InfoText>>;
+    info: InfoTranslations;
 }
 export interface StandaloneManifest {
     metadata?: PackageMetadata;
@@ -69,6 +66,8 @@ export interface StandaloneManifest {
     entry?: EntryMode;
     /** `portal`: registers the DSM Application Portal entry; an administrator activates it. */
     portal?: PortalDeclaration;
+    /** `icon`: a square PNG of at least 256 px, or a directory of icon_<size>.png; absent uses the SDK default. */
+    icon?: string;
 }
 /**
  * `admin-only`: DSM administrators only. `app-privilege`: administrators and

package/dist/standalone/manifest.js

@@ -4,7 +4,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { parse } from "yaml";
 import { isNativeArchFamily } from "../build-spk/dsm-arch.js";
-import { checkGlossary, isLocale, loadCatalogs } from "./i18n.js";
+import { checkGlossary, loadCatalogs, readInfoTranslations } from "./i18n.js";
 import { loadRootOps, ROOT_OPS_DIR } from "./root-ops.js";
 import { readDaemon } from "./daemon.js";
 import { readBackground } from "./background.js";
@@ -12,6 +12,7 @@ import { DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_MIN_DSM, portalMinDsmMessage } fr
 import { readSharedFolder } from "./shared-folder.js";
 import { floorAtAdministrators, permitsOrdinaryUsers, readApiPermissions } from "./api-permissions.js";
 import { readPortalDeclaration } from "../portal/alias.js";
+import { renderPackageIcons } from "../build-spk/dsm-icons.js";
 /**
  * `dsm-package.yaml`: a Standalone Package, i.e. an unsigned native SPK that
  * runs as its own DSM package account with a CGI backend and a DSM window UI.
@@ -19,10 +20,9 @@ import { readPortalDeclaration } from "../portal/alias.js";
 export const STANDALONE_MANIFEST = "dsm-package.yaml";
 export const KNOWN_FIELDS = new Set([
     "schema", "package", "version", "build", "displayname", "description",
-    "metadata", "maintainer", "os_min_ver", "arches", "backend", "ui", "capabilities", "i18n", "daemon", "install", "entry", "portal",
+    "metadata", "maintainer", "os_min_ver", "arches", "backend", "ui", "capabilities", "i18n", "daemon", "install", "entry", "portal", "icon",
 ]);
 const I18N_FIELDS = new Set(["messages", "glossary", "info"]);
-const INFO_TEXT_FIELDS = new Set(["displayname", "description"]);
 const PACKAGE_ID = /^[A-Za-z][A-Za-z0-9]{1,63}$/;
 const VERSION = /^\d+(\.\d+){0,3}$/;
 const OS_MIN_VER = /^\d+\.\d+(\.\d+)?-\d+$/;
@@ -154,6 +154,7 @@ function readManifest(raw, c) {
     if (capabilities.delegate?.scope === "install-selected" && ui && !ui.build)
         c.fail("CAPABILITY_COMBINATION_INVALID", "delegate scope install-selected 只能在 Vue 面板確認；plain UI 不支援，請改用 vue UI（init --ui vue）。");
     const i18n = raw.i18n === undefined ? undefined : readI18n(raw.i18n, c);
+    const icon = raw.icon === undefined ? undefined : readIcon(raw.icon, c);
     const portal = raw.portal === undefined || !packageId ? undefined : readPortalDeclaration(raw.portal, packageId)
         ?? c.fail("STANDALONE_PORTAL_INVALID", "portal 必須是 {} 或 { alias: <小寫英數與 -，1–64 字，不可為 DSM 保留路徑> }。");
     if (portal && osMinVer && !isDsmAtLeast(osMinVer, PORTAL_MIN_DSM)) {
@@ -185,8 +186,21 @@ function readManifest(raw, c) {
         ...(sharedFolder ? { sharedFolder } : {}),
         ...(entry ? { entry } : {}),
         ...(portal ? { portal } : {}),
+        ...(icon ? { icon } : {}),
     };
 }
+function readIcon(value, c) {
+    const path = c.path(value, "icon");
+    if (!path)
+        return undefined;
+    try {
+        renderPackageIcons(path);
+        return path;
+    }
+    catch (error) {
+        return c.fail("STANDALONE_ICON_INVALID", `icon：${error.message}`);
+    }
+}
 /**
  * The CGI enforces the entry mode only when the project's backend carries the
  * SDK gate and main wires it; `-X main.entry` on an older main would be
@@ -282,7 +296,10 @@ function readI18n(value, c) {
     if (!isRecord(value) || Object.keys(value).some((key) => !I18N_FIELDS.has(key))) {
         return invalid("只接受 messages（訊息目錄）、glossary（用語表）與 info（各語言 INFO 文字）。");
     }
-    const info = readInfoText(value.info, c);
+    const info = readInfoTranslations(value.info, {
+        invalid: (why) => c.fail("STANDALONE_I18N_INVALID", `i18n.info ${why}`),
+        text: (text, field) => c.text(text, field),
+    });
     if (value.messages === undefined) {
         return value.glossary === undefined ? info && { info } : invalid("glossary 需要搭配 messages。");
     }
@@ -300,36 +317,6 @@ function readI18n(value, c) {
     drift.forEach((e) => c.fail(e.code, e.message));
     return info && drift.length === 0 ? { catalogs: loaded.catalogs, info } : undefined;
 }
-function readInfoText(value, c) {
-    if (value === undefined) {
-        return {};
-    }
-    const invalid = (why) => c.fail("STANDALONE_I18N_INVALID", `i18n.info ${why}`);
-    if (!isRecord(value)) {
-        return invalid("必須以語言為 key，例如 zh-TW: { displayname, description }。");
-    }
-    const info = {};
-    for (const [locale, text] of Object.entries(value)) {
-        if (!isLocale(locale) || locale === "en") {
-            return invalid(`的「${locale}」不是支援的翻譯語言；英文寫在頂層 displayname / description。`);
-        }
-        if (!isRecord(text) || Object.keys(text).some((key) => !INFO_TEXT_FIELDS.has(key))) {
-            return invalid(`.${locale} 只接受 displayname 與 description。`);
-        }
-        const entry = {};
-        for (const field of INFO_TEXT_FIELDS) {
-            if (text[field] !== undefined) {
-                const checked = c.text(text[field], `i18n.info.${locale}.${field}`);
-                if (!checked) {
-                    return undefined;
-                }
-                entry[field] = checked;
-            }
-        }
-        info[locale] = entry;
-    }
-    return info;
-}
 /**
  * The nearest directory at or above `start` that holds dsm-package.yaml,
  * unless a Managed Profile project (synology-app.yaml) is found first.

package/dist/standalone/native-layout.d.ts

@@ -37,6 +37,8 @@ export interface NativeLayout {
     backend: {
         kind: 'native';
     };
+    /** Project-relative package icon; the CLI then owns PACKAGE_ICON*.PNG, the payload keeps its own window icons. */
+    icon?: string;
     layout: {
         payload: string;
         metadata: string;