@synopackageland/cli 0.7.3 → 0.9.0

package/dist/spk/rules.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Rules `synopkgland inspect` checks on any SPK, whoever built it. Each code
+ * is stable and keeps its severity: an error is something the Synology DSM 7
+ * Developer Guide requires; a warning is a likely mistake, or a rule the guide
+ * does not state clearly. `source` names the guide page the rule comes from.
+ */
+export type SpkRuleSeverity = "error" | "warning";
+export interface SpkRule {
+    severity: SpkRuleSeverity;
+    description: string;
+    source: string;
+}
+export declare const SPK_RULES: {
+    readonly SPK_NOT_TAR: {
+        readonly severity: "error";
+        readonly description: "檔案不是可讀的 tar 封存；SPK 是未壓縮的 tar。";
+        readonly source: "DSM 7 Developer Guide: Package Structure";
+    };
+    readonly SPK_ENTRY_UNSAFE: {
+        readonly severity: "error";
+        readonly description: "SPK 內的路徑跳出封存根目錄（絕對路徑或 ..），或是連結。";
+        readonly source: "DSM 7 Developer Guide: Package Structure";
+    };
+    readonly SPK_ENTRY_UNKNOWN: {
+        readonly severity: "warning";
+        readonly description: "SPK 最上層有指南沒有列出的檔案或目錄（檔名區分大小寫）。";
+        readonly source: "DSM 7 Developer Guide: Package Structure";
+    };
+    readonly SPK_INFO_MISSING: {
+        readonly severity: "error";
+        readonly description: "缺少 INFO。";
+        readonly source: "DSM 7 Developer Guide: Package Structure";
+    };
+    readonly SPK_PAYLOAD_MISSING: {
+        readonly severity: "error";
+        readonly description: "缺少 package.tgz。";
+        readonly source: "DSM 7 Developer Guide: Package Structure";
+    };
+    readonly SPK_INFO_FIELD_REQUIRED: {
+        readonly severity: "error";
+        readonly description: "INFO 缺少必填欄位（package、version、os_min_ver、description、arch、maintainer）。";
+        readonly source: "DSM 7 Developer Guide: INFO Necessary Fields";
+    };
+    readonly SPK_INFO_DISPLAYNAME_MISSING: {
+        readonly severity: "warning";
+        readonly description: "INFO 沒有 displayname；Package Center 會改顯示 package 值。";
+        readonly source: "DSM 7 Developer Guide: INFO Optional Fields";
+    };
+    readonly SPK_INFO_LINE_INVALID: {
+        readonly severity: "warning";
+        readonly description: "INFO 有一行不是 key=\"value\"（空行與 # 註解除外）。";
+        readonly source: "DSM 7 Developer Guide: INFO";
+    };
+    readonly SPK_INFO_VALUE_UNTERMINATED: {
+        readonly severity: "error";
+        readonly description: "INFO 欄位值的引號沒有結束。";
+        readonly source: "DSM 7 Developer Guide: INFO";
+    };
+    readonly SPK_INFO_FIELD_DUPLICATE: {
+        readonly severity: "warning";
+        readonly description: "INFO 同一個欄位設定了兩次。";
+        readonly source: "DSM 7 Developer Guide: INFO";
+    };
+    readonly SPK_INFO_PACKAGE_INVALID: {
+        readonly severity: "error";
+        readonly description: "INFO package 含有 : / > < | = 其中之一。";
+        readonly source: "DSM 7 Developer Guide: INFO Necessary Fields (package)";
+    };
+    readonly SPK_INFO_VERSION_INVALID: {
+        readonly severity: "error";
+        readonly description: "INFO version 不是以 .、-、_ 分隔的數字，或某段超過 2147483647。";
+        readonly source: "DSM 7 Developer Guide: INFO Necessary Fields (version)";
+    };
+    readonly SPK_INFO_VERSION_NO_BUILD: {
+        readonly severity: "warning";
+        readonly description: "INFO version 沒有 -<build> 編號（指南格式為 [feature number]-[build number]）。";
+        readonly source: "DSM 7 Developer Guide: INFO Necessary Fields (version)";
+    };
+    readonly SPK_INFO_OS_VER_INVALID: {
+        readonly severity: "error";
+        readonly description: "INFO os_min_ver 或 os_max_ver 不是 <major>.<minor>-<build>（也接受 <major>.<minor>.<micro>-<build>）。";
+        readonly source: "DSM 7 Developer Guide: INFO Necessary Fields (os_min_ver), Optional Fields (os_max_ver)";
+    };
+    readonly SPK_INFO_OS_MIN_VER_LOW: {
+        readonly severity: "warning";
+        readonly description: "INFO os_min_ver 低於 7.0-40000。";
+        readonly source: "DSM 7 Developer Guide: INFO Necessary Fields (os_min_ver)";
+    };
+    readonly SPK_INFO_ARCH_UNKNOWN: {
+        readonly severity: "warning";
+        readonly description: "INFO arch 或 exclude_arch 含有 Appendix A 與已知 DSM 7 平台都沒有的值。";
+        readonly source: "DSM 7 Developer Guide: Appendix A Platform and Arch Value Mapping Table";
+    };
+    readonly SPK_INFO_ARCH_NOARCH_MIXED: {
+        readonly severity: "warning";
+        readonly description: "INFO arch 同時有 noarch 與其他值。";
+        readonly source: "DSM 7 Developer Guide: INFO Necessary Fields (arch)";
+    };
+    readonly SPK_INFO_BOOLEAN_INVALID: {
+        readonly severity: "error";
+        readonly description: "INFO 的 yes/no 欄位（例如 startable、silent_install）不是 \"yes\" 或 \"no\"。";
+        readonly source: "DSM 7 Developer Guide: INFO Optional Fields";
+    };
+    readonly SPK_INFO_LANG_UNKNOWN: {
+        readonly severity: "warning";
+        readonly description: "displayname_<lang> 或 description_<lang> 的語言碼不在指南清單（enu、cht、chs、jpn…）。";
+        readonly source: "DSM 7 Developer Guide: INFO Optional Fields (description_[language])";
+    };
+    readonly SPK_INFO_FIELD_UNKNOWN: {
+        readonly severity: "warning";
+        readonly description: "INFO 欄位不在指南清單；DSM 不會使用它（拼錯的欄位名稱也會出現在這裡）。";
+        readonly source: "DSM 7 Developer Guide: INFO Necessary Fields, Optional Fields";
+    };
+    readonly SPK_INFO_ADMINPORT_INVALID: {
+        readonly severity: "error";
+        readonly description: "INFO adminport 不是 0–65536 的整數。";
+        readonly source: "DSM 7 Developer Guide: INFO Optional Fields (adminport)";
+    };
+    readonly SPK_INFO_CHECKSUM_MISMATCH: {
+        readonly severity: "error";
+        readonly description: "INFO checksum 不是 package.tgz 的 MD5。";
+        readonly source: "DSM 7 Developer Guide: INFO Optional Fields (checksum)";
+    };
+    readonly SPK_PAYLOAD_UNREADABLE: {
+        readonly severity: "error";
+        readonly description: "package.tgz 不是可讀的 tar 或 tar.gz 封存，或是空的。";
+        readonly source: "DSM 7 Developer Guide: Package Structure (package.tgz)";
+    };
+    readonly SPK_PAYLOAD_XZ: {
+        readonly severity: "warning";
+        readonly description: "package.tgz 是 xz 壓縮（Synology toolkit 的格式）；inspect 讀不了 xz，沒有檢查 payload 內容。";
+        readonly source: "DSM 7 Developer Guide: Pack Stage";
+    };
+    readonly SPK_PAYLOAD_PATH_UNSAFE: {
+        readonly severity: "error";
+        readonly description: "package.tgz 的路徑是絕對路徑或含 ..，會解開到套件目錄之外。";
+        readonly source: "DSM 7 Developer Guide: Package Structure (package.tgz)";
+    };
+    readonly SPK_PAYLOAD_LINK_ESCAPE: {
+        readonly severity: "error";
+        readonly description: "package.tgz 的 symlink 或 hard link 指到套件目錄之外。";
+        readonly source: "DSM 7 Developer Guide: Package Structure (package.tgz)";
+    };
+    readonly SPK_PAYLOAD_LINK_ABSOLUTE: {
+        readonly severity: "warning";
+        readonly description: "package.tgz 的 symlink 指向絕對路徑；目標由 NAS 決定，不在套件內。";
+        readonly source: "DSM 7 Developer Guide: Package Structure (package.tgz)";
+    };
+    readonly SPK_UI_CONFIG_INVALID: {
+        readonly severity: "error";
+        readonly description: "dsmuidir 底下的 config 不是 JSON 物件。";
+        readonly source: "DSM 7 Developer Guide: Integrate DSM, Application Config";
+    };
+    readonly SPK_UI_TEXTS_MISSING: {
+        readonly severity: "error";
+        readonly description: "config 的 title／desc 參照套件自己的字串（例如 synopkgland:app_title），但該 entry 沒有宣告 \"texts\"；DSM 會直接顯示 key。";
+        readonly source: "DSM 7.1.1／7.4 實測（DSM 只為宣告 texts 的 entry 載入 texts/<lang>/strings）";
+    };
+    readonly SPK_UI_TEXTS_UNDECLARED: {
+        readonly severity: "warning";
+        readonly description: "config 的 title／desc 是 section:key 字串參照，但沒有宣告 \"texts\"；除非是 DSM 內建 section，否則 DSM 會直接顯示 key。";
+        readonly source: "DSM 7.1.1／7.4 實測";
+    };
+    readonly SPK_NOARCH_ELF: {
+        readonly severity: "error";
+        readonly description: "INFO arch 是 noarch，但 package.tgz 有 ELF 執行檔。";
+        readonly source: "DSM 7 Developer Guide: INFO Necessary Fields (arch)、Pack Stage";
+    };
+    readonly SPK_ELF_ARCH_MISMATCH: {
+        readonly severity: "error";
+        readonly description: "package.tgz 的 ELF 執行檔與 INFO arch 的 CPU 不符。";
+        readonly source: "DSM 7 Developer Guide: INFO Necessary Fields (arch)、Appendix A";
+    };
+    readonly SPK_SCRIPT_MISSING: {
+        readonly severity: "error";
+        readonly description: "缺少 scripts/start-stop-status；DSM 用它啟動、停止與查詢套件狀態。";
+        readonly source: "DSM 7 Developer Guide: Package Structure、scripts";
+    };
+    readonly SPK_SCRIPT_HOOK_MISSING: {
+        readonly severity: "warning";
+        readonly description: "缺少 preinst、postinst、preuninst、postuninst、preupgrade 或 postupgrade；指南列為必備，DSM 缺檔時的行為未驗證。";
+        readonly source: "DSM 7 Developer Guide: scripts";
+    };
+    readonly SPK_SCRIPT_NOT_EXECUTABLE: {
+        readonly severity: "error";
+        readonly description: "scripts/ 的生命週期腳本沒有執行權限。";
+        readonly source: "DSM 7 Developer Guide: scripts";
+    };
+    readonly SPK_SCRIPT_NO_INTERPRETER: {
+        readonly severity: "warning";
+        readonly description: "生命週期腳本開頭沒有 #!（例如 #!/bin/sh），也不是 ELF。";
+        readonly source: "DSM 7 Developer Guide: scripts";
+    };
+    readonly SPK_PRIVILEGE_MISSING: {
+        readonly severity: "error";
+        readonly description: "缺少 conf/privilege；DSM 7 起必須提供。";
+        readonly source: "DSM 7 Developer Guide: conf、Privilege Config";
+    };
+    readonly SPK_PRIVILEGE_INVALID: {
+        readonly severity: "error";
+        readonly description: "conf/privilege 不是 JSON 物件、沒有 defaults.run-as，或 run-as 不是 package／root。";
+        readonly source: "DSM 7 Developer Guide: Privilege Config";
+    };
+    readonly SPK_PRIVILEGE_ROOT: {
+        readonly severity: "warning";
+        readonly description: "conf/privilege 要求以 root 執行（defaults、ctrl-script 或 executable）。";
+        readonly source: "DSM 7 Developer Guide: Privilege Config";
+    };
+    readonly SPK_RESOURCE_INVALID: {
+        readonly severity: "error";
+        readonly description: "conf/resource 不是 JSON 物件。";
+        readonly source: "DSM 7 Developer Guide: Resource Config";
+    };
+    readonly SPK_RESOURCE_UNKNOWN: {
+        readonly severity: "warning";
+        readonly description: "conf/resource 有指南沒有列出的 resource worker id。";
+        readonly source: "DSM 7 Developer Guide: Available Workers";
+    };
+    readonly SPK_CONF_UNKNOWN: {
+        readonly severity: "warning";
+        readonly description: "conf/ 有 DSM 不讀取的檔案（已知：privilege、resource、PKG_DEPS、PKG_CONX、systemd/）。";
+        readonly source: "DSM 7 Developer Guide: conf、Systemd User Unit";
+    };
+    readonly SPK_ICON_MISSING: {
+        readonly severity: "error";
+        readonly description: "缺少 PACKAGE_ICON.PNG 或 PACKAGE_ICON_256.PNG。";
+        readonly source: "DSM 7 Developer Guide: Package Structure";
+    };
+    readonly SPK_ICON_INVALID: {
+        readonly severity: "error";
+        readonly description: "PACKAGE_ICON.PNG 或 PACKAGE_ICON_256.PNG 不是 PNG。";
+        readonly source: "DSM 7 Developer Guide: Package Structure";
+    };
+    readonly SPK_ICON_SIZE: {
+        readonly severity: "warning";
+        readonly description: "PACKAGE_ICON.PNG 不是 64×64，或 PACKAGE_ICON_256.PNG 不是 256×256。";
+        readonly source: "DSM 7 Developer Guide: Package Structure";
+    };
+    readonly SPK_LICENSE_TOO_LARGE: {
+        readonly severity: "error";
+        readonly description: "LICENSE 大於或等於 1 MB。";
+        readonly source: "DSM 7 Developer Guide: Package Structure";
+    };
+    readonly SPK_WIZARD_INVALID: {
+        readonly severity: "warning";
+        readonly description: "WIZARD_UIFILES 的精靈檔不是 JSON 陣列。";
+        readonly source: "DSM 7 Developer Guide: Package Structure (WIZARD_UIFILES)";
+    };
+    readonly SPK_WIZARD_SCRIPT_NOT_EXECUTABLE: {
+        readonly severity: "warning";
+        readonly description: "WIZARD_UIFILES 的 .sh 精靈產生器沒有執行權限。";
+        readonly source: "DSM 7 Developer Guide: Package Structure (WIZARD_UIFILES)";
+    };
+    readonly SPK_WIZARD_UNKNOWN: {
+        readonly severity: "warning";
+        readonly description: "WIZARD_UIFILES 的檔名不是 install／upgrade／uninstall_uifile[_<lang>][.sh]。";
+        readonly source: "DSM 7 Developer Guide: Package Structure (WIZARD_UIFILES)";
+    };
+    readonly SPK_SIGNATURE_INVALID: {
+        readonly severity: "warning";
+        readonly description: "syno_signature.asc 不是 ASCII-armored PGP 簽章（指南的套件簽章只適用 DSM 6.x，可省略此檔）。";
+        readonly source: "DSM 7 Developer Guide: Sign Package (only for DSM6.X)";
+    };
+};
+export type SpkRuleCode = keyof typeof SPK_RULES;

package/dist/spk/rules.js

@@ -0,0 +1,53 @@
+const GUIDE = "DSM 7 Developer Guide";
+export const SPK_RULES = {
+    SPK_NOT_TAR: { severity: "error", description: "檔案不是可讀的 tar 封存；SPK 是未壓縮的 tar。", source: `${GUIDE}: Package Structure` },
+    SPK_ENTRY_UNSAFE: { severity: "error", description: "SPK 內的路徑跳出封存根目錄（絕對路徑或 ..），或是連結。", source: `${GUIDE}: Package Structure` },
+    SPK_ENTRY_UNKNOWN: { severity: "warning", description: "SPK 最上層有指南沒有列出的檔案或目錄（檔名區分大小寫）。", source: `${GUIDE}: Package Structure` },
+    SPK_INFO_MISSING: { severity: "error", description: "缺少 INFO。", source: `${GUIDE}: Package Structure` },
+    SPK_PAYLOAD_MISSING: { severity: "error", description: "缺少 package.tgz。", source: `${GUIDE}: Package Structure` },
+    SPK_INFO_FIELD_REQUIRED: { severity: "error", description: "INFO 缺少必填欄位（package、version、os_min_ver、description、arch、maintainer）。", source: `${GUIDE}: INFO Necessary Fields` },
+    SPK_INFO_DISPLAYNAME_MISSING: { severity: "warning", description: "INFO 沒有 displayname；Package Center 會改顯示 package 值。", source: `${GUIDE}: INFO Optional Fields` },
+    SPK_INFO_LINE_INVALID: { severity: "warning", description: "INFO 有一行不是 key=\"value\"（空行與 # 註解除外）。", source: `${GUIDE}: INFO` },
+    SPK_INFO_VALUE_UNTERMINATED: { severity: "error", description: "INFO 欄位值的引號沒有結束。", source: `${GUIDE}: INFO` },
+    SPK_INFO_FIELD_DUPLICATE: { severity: "warning", description: "INFO 同一個欄位設定了兩次。", source: `${GUIDE}: INFO` },
+    SPK_INFO_PACKAGE_INVALID: { severity: "error", description: "INFO package 含有 : / > < | = 其中之一。", source: `${GUIDE}: INFO Necessary Fields (package)` },
+    SPK_INFO_VERSION_INVALID: { severity: "error", description: "INFO version 不是以 .、-、_ 分隔的數字，或某段超過 2147483647。", source: `${GUIDE}: INFO Necessary Fields (version)` },
+    SPK_INFO_VERSION_NO_BUILD: { severity: "warning", description: "INFO version 沒有 -<build> 編號（指南格式為 [feature number]-[build number]）。", source: `${GUIDE}: INFO Necessary Fields (version)` },
+    SPK_INFO_OS_VER_INVALID: { severity: "error", description: "INFO os_min_ver 或 os_max_ver 不是 <major>.<minor>-<build>（也接受 <major>.<minor>.<micro>-<build>）。", source: `${GUIDE}: INFO Necessary Fields (os_min_ver), Optional Fields (os_max_ver)` },
+    SPK_INFO_OS_MIN_VER_LOW: { severity: "warning", description: "INFO os_min_ver 低於 7.0-40000。", source: `${GUIDE}: INFO Necessary Fields (os_min_ver)` },
+    SPK_INFO_ARCH_UNKNOWN: { severity: "warning", description: "INFO arch 或 exclude_arch 含有 Appendix A 與已知 DSM 7 平台都沒有的值。", source: `${GUIDE}: Appendix A Platform and Arch Value Mapping Table` },
+    SPK_INFO_ARCH_NOARCH_MIXED: { severity: "warning", description: "INFO arch 同時有 noarch 與其他值。", source: `${GUIDE}: INFO Necessary Fields (arch)` },
+    SPK_INFO_BOOLEAN_INVALID: { severity: "error", description: "INFO 的 yes/no 欄位（例如 startable、silent_install）不是 \"yes\" 或 \"no\"。", source: `${GUIDE}: INFO Optional Fields` },
+    SPK_INFO_LANG_UNKNOWN: { severity: "warning", description: "displayname_<lang> 或 description_<lang> 的語言碼不在指南清單（enu、cht、chs、jpn…）。", source: `${GUIDE}: INFO Optional Fields (description_[language])` },
+    SPK_INFO_FIELD_UNKNOWN: { severity: "warning", description: "INFO 欄位不在指南清單；DSM 不會使用它（拼錯的欄位名稱也會出現在這裡）。", source: `${GUIDE}: INFO Necessary Fields, Optional Fields` },
+    SPK_INFO_ADMINPORT_INVALID: { severity: "error", description: "INFO adminport 不是 0–65536 的整數。", source: `${GUIDE}: INFO Optional Fields (adminport)` },
+    SPK_INFO_CHECKSUM_MISMATCH: { severity: "error", description: "INFO checksum 不是 package.tgz 的 MD5。", source: `${GUIDE}: INFO Optional Fields (checksum)` },
+    SPK_PAYLOAD_UNREADABLE: { severity: "error", description: "package.tgz 不是可讀的 tar 或 tar.gz 封存，或是空的。", source: `${GUIDE}: Package Structure (package.tgz)` },
+    SPK_PAYLOAD_XZ: { severity: "warning", description: "package.tgz 是 xz 壓縮（Synology toolkit 的格式）；inspect 讀不了 xz，沒有檢查 payload 內容。", source: `${GUIDE}: Pack Stage` },
+    SPK_PAYLOAD_PATH_UNSAFE: { severity: "error", description: "package.tgz 的路徑是絕對路徑或含 ..，會解開到套件目錄之外。", source: `${GUIDE}: Package Structure (package.tgz)` },
+    SPK_PAYLOAD_LINK_ESCAPE: { severity: "error", description: "package.tgz 的 symlink 或 hard link 指到套件目錄之外。", source: `${GUIDE}: Package Structure (package.tgz)` },
+    SPK_PAYLOAD_LINK_ABSOLUTE: { severity: "warning", description: "package.tgz 的 symlink 指向絕對路徑；目標由 NAS 決定，不在套件內。", source: `${GUIDE}: Package Structure (package.tgz)` },
+    SPK_UI_CONFIG_INVALID: { severity: "error", description: "dsmuidir 底下的 config 不是 JSON 物件。", source: `${GUIDE}: Integrate DSM, Application Config` },
+    SPK_UI_TEXTS_MISSING: { severity: "error", description: "config 的 title／desc 參照套件自己的字串（例如 synopkgland:app_title），但該 entry 沒有宣告 \"texts\"；DSM 會直接顯示 key。", source: "DSM 7.1.1／7.4 實測（DSM 只為宣告 texts 的 entry 載入 texts/<lang>/strings）" },
+    SPK_UI_TEXTS_UNDECLARED: { severity: "warning", description: "config 的 title／desc 是 section:key 字串參照，但沒有宣告 \"texts\"；除非是 DSM 內建 section，否則 DSM 會直接顯示 key。", source: "DSM 7.1.1／7.4 實測" },
+    SPK_NOARCH_ELF: { severity: "error", description: "INFO arch 是 noarch，但 package.tgz 有 ELF 執行檔。", source: `${GUIDE}: INFO Necessary Fields (arch)、Pack Stage` },
+    SPK_ELF_ARCH_MISMATCH: { severity: "error", description: "package.tgz 的 ELF 執行檔與 INFO arch 的 CPU 不符。", source: `${GUIDE}: INFO Necessary Fields (arch)、Appendix A` },
+    SPK_SCRIPT_MISSING: { severity: "error", description: "缺少 scripts/start-stop-status；DSM 用它啟動、停止與查詢套件狀態。", source: `${GUIDE}: Package Structure、scripts` },
+    SPK_SCRIPT_HOOK_MISSING: { severity: "warning", description: "缺少 preinst、postinst、preuninst、postuninst、preupgrade 或 postupgrade；指南列為必備，DSM 缺檔時的行為未驗證。", source: `${GUIDE}: scripts` },
+    SPK_SCRIPT_NOT_EXECUTABLE: { severity: "error", description: "scripts/ 的生命週期腳本沒有執行權限。", source: `${GUIDE}: scripts` },
+    SPK_SCRIPT_NO_INTERPRETER: { severity: "warning", description: "生命週期腳本開頭沒有 #!（例如 #!/bin/sh），也不是 ELF。", source: `${GUIDE}: scripts` },
+    SPK_PRIVILEGE_MISSING: { severity: "error", description: "缺少 conf/privilege；DSM 7 起必須提供。", source: `${GUIDE}: conf、Privilege Config` },
+    SPK_PRIVILEGE_INVALID: { severity: "error", description: "conf/privilege 不是 JSON 物件、沒有 defaults.run-as，或 run-as 不是 package／root。", source: `${GUIDE}: Privilege Config` },
+    SPK_PRIVILEGE_ROOT: { severity: "warning", description: "conf/privilege 要求以 root 執行（defaults、ctrl-script 或 executable）。", source: `${GUIDE}: Privilege Config` },
+    SPK_RESOURCE_INVALID: { severity: "error", description: "conf/resource 不是 JSON 物件。", source: `${GUIDE}: Resource Config` },
+    SPK_RESOURCE_UNKNOWN: { severity: "warning", description: "conf/resource 有指南沒有列出的 resource worker id。", source: `${GUIDE}: Available Workers` },
+    SPK_CONF_UNKNOWN: { severity: "warning", description: "conf/ 有 DSM 不讀取的檔案（已知：privilege、resource、PKG_DEPS、PKG_CONX、systemd/）。", source: `${GUIDE}: conf、Systemd User Unit` },
+    SPK_ICON_MISSING: { severity: "error", description: "缺少 PACKAGE_ICON.PNG 或 PACKAGE_ICON_256.PNG。", source: `${GUIDE}: Package Structure` },
+    SPK_ICON_INVALID: { severity: "error", description: "PACKAGE_ICON.PNG 或 PACKAGE_ICON_256.PNG 不是 PNG。", source: `${GUIDE}: Package Structure` },
+    SPK_ICON_SIZE: { severity: "warning", description: "PACKAGE_ICON.PNG 不是 64×64，或 PACKAGE_ICON_256.PNG 不是 256×256。", source: `${GUIDE}: Package Structure` },
+    SPK_LICENSE_TOO_LARGE: { severity: "error", description: "LICENSE 大於或等於 1 MB。", source: `${GUIDE}: Package Structure` },
+    SPK_WIZARD_INVALID: { severity: "warning", description: "WIZARD_UIFILES 的精靈檔不是 JSON 陣列。", source: `${GUIDE}: Package Structure (WIZARD_UIFILES)` },
+    SPK_WIZARD_SCRIPT_NOT_EXECUTABLE: { severity: "warning", description: "WIZARD_UIFILES 的 .sh 精靈產生器沒有執行權限。", source: `${GUIDE}: Package Structure (WIZARD_UIFILES)` },
+    SPK_WIZARD_UNKNOWN: { severity: "warning", description: "WIZARD_UIFILES 的檔名不是 install／upgrade／uninstall_uifile[_<lang>][.sh]。", source: `${GUIDE}: Package Structure (WIZARD_UIFILES)` },
+    SPK_SIGNATURE_INVALID: { severity: "warning", description: "syno_signature.asc 不是 ASCII-armored PGP 簽章（指南的套件簽章只適用 DSM 6.x，可省略此檔）。", source: `${GUIDE}: Sign Package (only for DSM6.X)` },
+};

package/dist/spk/validate-spk.d.ts

@@ -0,0 +1,13 @@
+import { type SpkFinding } from "./findings.js";
+export type { SpkFinding } from "./findings.js";
+export interface SpkValidation {
+    /** No errors; warnings do not fail validation. */
+    ok: boolean;
+    package?: string;
+    version?: string;
+    arch?: string;
+    errors: SpkFinding[];
+    warnings: SpkFinding[];
+}
+/** Checks an SPK against the DSM 7 package format without installing or running anything. */
+export declare function validateSpk(spkPath: string): Promise<SpkValidation>;

package/dist/spk/validate-spk.js

@@ -0,0 +1,107 @@
+import { createWriteStream, mkdtempSync, rmSync } from "node:fs";
+import { finished } from "node:stream/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import * as tar from "tar";
+import { checkInfoFields, parseInfo } from "./check-info.js";
+import { checkMetadata } from "./check-metadata.js";
+import { checkPayload } from "./check-payload.js";
+import { KNOWN_TOP_LEVEL } from "./dsm-spec.js";
+import { Findings } from "./findings.js";
+/** Outer files other than package.tgz are metadata; anything larger is not read. */
+const MAX_OUTER_FILE = 16 * 1024 * 1024;
+const TOP_LEVEL = new Set(KNOWN_TOP_LEVEL);
+/** Checks an SPK against the DSM 7 package format without installing or running anything. */
+export async function validateSpk(spkPath) {
+    const findings = new Findings();
+    const dir = mkdtempSync(join(tmpdir(), "syno-validate-spk-"));
+    let info = {};
+    try {
+        const outer = await readOuter(spkPath, dir, findings);
+        if (outer) {
+            checkOuterEntries(outer.entries, findings);
+            info = checkInfo(outer, findings);
+            if (!outer.payloadPath)
+                findings.add("SPK_PAYLOAD_MISSING", "缺少 package.tgz。", "package.tgz");
+            else
+                await checkPayload(outer.payloadPath, info, findings);
+            checkMetadata({ files: outer.files, modes: new Map(outer.entries.map((entry) => [normalize(entry.path), entry.mode])) }, findings);
+        }
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    const errors = findings.list.filter((finding) => finding.severity === "error");
+    return {
+        ok: errors.length === 0,
+        ...(info.package ? { package: info.package } : {}),
+        ...(info.version ? { version: info.version } : {}),
+        ...(info.arch ? { arch: info.arch } : {}),
+        errors,
+        warnings: findings.list.filter((finding) => finding.severity === "warning"),
+    };
+}
+/** One pass over the outer tar; nothing is extracted by name, so case-only differences stay distinct. */
+async function readOuter(spkPath, dir, findings) {
+    const outer = { entries: [], files: new Map() };
+    const writes = [];
+    try {
+        await tar.t({
+            file: spkPath,
+            strict: true,
+            onReadEntry: (entry) => {
+                outer.entries.push({ path: entry.path, type: entry.type, mode: (entry.mode ?? 0) & 0o7777 });
+                const path = normalize(entry.path);
+                if (entry.type !== "File" || !isSafeOuter(entry.path, entry.type))
+                    return;
+                if (path === "package.tgz") {
+                    outer.payloadPath = join(dir, "package.tgz");
+                    writes.push(finished(entry.pipe(createWriteStream(outer.payloadPath))));
+                }
+                else if ((entry.size ?? 0) <= MAX_OUTER_FILE) {
+                    const chunks = [];
+                    entry.on("data", (chunk) => chunks.push(chunk));
+                    entry.on("end", () => outer.files.set(path, Buffer.concat(chunks)));
+                }
+            },
+        });
+        await Promise.all(writes);
+    }
+    catch {
+        outer.entries.length = 0;
+    }
+    if (outer.entries.length === 0) {
+        findings.add("SPK_NOT_TAR", "檔案不是可讀的 tar 封存。");
+        return undefined;
+    }
+    return outer;
+}
+function normalize(path) {
+    return path.replace(/^\.\//, "").replace(/\/$/, "");
+}
+function isSafeOuter(path, type) {
+    return !path.startsWith("/") && !normalize(path).split("/").includes("..") && type !== "SymbolicLink" && type !== "Link";
+}
+function checkOuterEntries(entries, findings) {
+    for (const entry of entries) {
+        const path = normalize(entry.path);
+        if (!isSafeOuter(entry.path, entry.type)) {
+            findings.add("SPK_ENTRY_UNSAFE", `${entry.path} 跳出 SPK 根目錄或是連結；DSM 只解開一般檔案與目錄。`, entry.path);
+            continue;
+        }
+        const top = path.split("/")[0];
+        if (top && !TOP_LEVEL.has(top)) {
+            findings.add("SPK_ENTRY_UNKNOWN", `${top} 不是 SPK 最上層的已知檔案（檔名區分大小寫）。`, top);
+        }
+    }
+}
+function checkInfo(outer, findings) {
+    const text = outer.files.get("INFO");
+    if (text === undefined) {
+        findings.add("SPK_INFO_MISSING", "缺少 INFO。", "INFO");
+        return {};
+    }
+    const fields = parseInfo(text.toString("utf8"), findings);
+    checkInfoFields(fields, outer.payloadPath, findings);
+    return Object.fromEntries(fields);
+}

package/dist/standalone/api-permissions.d.ts

@@ -1,5 +1,6 @@
 import type { Capabilities } from "./manifest.js";
 export declare const API_PERMISSIONS_FILE = "internal/api/permissions.json";
+type SdkPermissions = Record<string, Record<string, ApiPermission>>;
 export declare const MAX_PERMISSIONS_BYTES = 65536;
 export declare const MAX_PERMISSION_METHODS = 1024;
 export type ApiPermission = "administrators" | "authenticated" | "public";
@@ -13,6 +14,7 @@ export declare function readApiPermissions(backendDir: string, capabilities?: Ca
     policy: ApiPermissions;
     digest: string;
     sdkDigest: string;
+    sdk: SdkPermissions;
 };
 /**
  * `entry: admin-only` makes administrators the floor of every route. App
@@ -20,9 +22,10 @@ export declare function readApiPermissions(backendDir: string, capabilities?: Ca
  * capability added are raised, except the public login ceremony of
  * `identity: standalone`, which admits no one by itself.
  */
-export declare function floorAtAdministrators(policy: ApiPermissions): {
+export declare function floorAtAdministrators(policy: ApiPermissions, sdkPermissions: SdkPermissions): {
     policy: ApiPermissions;
     widened: string[];
 };
 /** Launcher access is derived from the same API policy; no second setting. */
 export declare function permitsOrdinaryUsers(policy?: ApiPermissions): boolean;
+export {};

package/dist/standalone/api-permissions.js

@@ -1,10 +1,11 @@
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { templatesRoot } from "../template-paths.js";
+import { sdkRequirement, sdkSource } from "../runtime/sdk-source.js";
 import { parseDocument } from "yaml";
 export const API_PERMISSIONS_FILE = "internal/api/permissions.json";
-const SDK_PERMISSIONS_TEMPLATE = "native-go/backend/internal/api/sdk-permissions.json";
+/** SDK-owned routes per capability, in the Go module of the SDK version the App requires. */
+const SDK_PERMISSIONS_FILE = "api/sdk-permissions.json";
 export const MAX_PERMISSIONS_BYTES = 65536;
 export const MAX_PERMISSION_METHODS = 1024;
 export function parseApiPermissions(raw) {
@@ -38,15 +39,9 @@ export function readApiPermissions(backendDir, capabilities = {}) {
         throw new Error("permissions must be a regular bounded JSON file");
     const raw = readFileSync(file);
     const policy = parseApiPermissions(raw);
-    const sdkRaw = readFileSync(join(templatesRoot(), SDK_PERMISSIONS_TEMPLATE));
-    const sdkFile = join(backendDir, 'internal/api/sdk-permissions.json');
-    if (existsSync(sdkFile)) {
-        const sdkStat = lstatSync(sdkFile);
-        if (!sdkStat.isFile() || sdkStat.size !== sdkRaw.length || !readFileSync(sdkFile).equals(sdkRaw)) {
-            throw new Error('SDK route policy differs from the CLI policy; restore the SDK-owned file');
-        }
-    }
-    const sdk = readSdkPermissions();
+    const version = sdkRequirement(backendDir);
+    const sdkRaw = version ? readFileSync(join(sdkSource(version).goDir, SDK_PERMISSIONS_FILE)) : Buffer.from("{}");
+    const sdk = JSON.parse(sdkRaw.toString("utf8"));
     for (const methods of Object.values(sdk))
         for (const method of Object.keys(methods)) {
             if (Object.hasOwn(policy.methods, method))
@@ -56,7 +51,7 @@ export function readApiPermissions(backendDir, capabilities = {}) {
         if (capabilities[capability] || ['rootOps', 'files'].includes(capability) && capabilities.delegate)
             Object.assign(policy.methods, methods);
     }
-    return { policy, sdkDigest: createHash("sha256").update(sdkRaw).digest("hex"), digest: createHash("sha256").update(raw).digest("hex") };
+    return { policy, sdk, sdkDigest: createHash("sha256").update(sdkRaw).digest("hex"), digest: createHash("sha256").update(raw).digest("hex") };
 }
 /**
  * `entry: admin-only` makes administrators the floor of every route. App
@@ -64,16 +59,13 @@ export function readApiPermissions(backendDir, capabilities = {}) {
  * capability added are raised, except the public login ceremony of
  * `identity: standalone`, which admits no one by itself.
  */
-export function floorAtAdministrators(policy) {
-    const sdk = new Set(Object.values(readSdkPermissions()).flatMap(methods => Object.keys(methods)));
+export function floorAtAdministrators(policy, sdkPermissions) {
+    const sdk = new Set(Object.values(sdkPermissions).flatMap(methods => Object.keys(methods)));
     const methods = Object.fromEntries(Object.entries(policy.methods)
         .map(([method, permission]) => [method, sdk.has(method) && permission === "public" ? permission : "administrators"]));
     const widened = Object.entries(policy.methods).filter(([method, permission]) => !sdk.has(method) && permission !== "administrators").map(([method]) => method);
     return { policy: { ...policy, methods }, widened };
 }
-function readSdkPermissions() {
-    return JSON.parse(readFileSync(join(templatesRoot(), SDK_PERMISSIONS_TEMPLATE), 'utf8'));
-}
 /** Launcher access is derived from the same API policy; no second setting. */
 export function permitsOrdinaryUsers(policy) {
     return policy !== undefined && Object.values(policy.methods).some(permission => permission !== "administrators");

package/dist/standalone/arch-jobs.d.ts

@@ -0,0 +1,11 @@
+/** `--jobs`: how many architectures build at once; 1 keeps the sequential build. */
+export declare function checkJobs(jobs?: number): number;
+/**
+ * Builds each architecture, at most `jobs` at a time, and returns the results in
+ * `arches` order. After a failure no further architecture starts; running ones
+ * finish so they clean up. The first failure in `arches` order is rethrown with
+ * `[arch]` in front of its message.
+ */
+export declare function forEachArch<A extends string, T>(arches: readonly A[], jobs: number, build: (arch: A) => Promise<T>): Promise<T[]>;
+/** Builds every SPK in a private folder inside `outDir` and moves them into `outDir` only when all of them succeed. */
+export declare function commitOutputs(outDir: string, build: (stage: string) => Promise<string[]>): Promise<string[]>;

package/dist/standalone/arch-jobs.js

@@ -0,0 +1,54 @@
+import { mkdirSync, mkdtempSync, renameSync, rmSync } from "node:fs";
+import { basename, join } from "node:path";
+/** `--jobs`: how many architectures build at once; 1 keeps the sequential build. */
+export function checkJobs(jobs = 1) {
+    if (!Number.isSafeInteger(jobs) || jobs < 1) {
+        throw Object.assign(new Error(`[CLI_JOBS_INVALID] --jobs must be a positive integer, got ${jobs}.`), { code: "CLI_JOBS_INVALID" });
+    }
+    return jobs;
+}
+/**
+ * Builds each architecture, at most `jobs` at a time, and returns the results in
+ * `arches` order. After a failure no further architecture starts; running ones
+ * finish so they clean up. The first failure in `arches` order is rethrown with
+ * `[arch]` in front of its message.
+ */
+export async function forEachArch(arches, jobs, build) {
+    const results = [];
+    const failures = [];
+    let next = 0;
+    const worker = async () => {
+        while (next < arches.length && !failures.length) {
+            const index = next++;
+            try {
+                results[index] = await build(arches[index]);
+            }
+            catch (error) {
+                failures.push({ index, error });
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(checkJobs(jobs), arches.length) }, worker));
+    const [first] = failures.sort((a, b) => a.index - b.index);
+    if (first) {
+        if (first.error instanceof Error)
+            first.error.message = `[${arches[first.index]}] ${first.error.message}`;
+        throw first.error;
+    }
+    return results;
+}
+/** Builds every SPK in a private folder inside `outDir` and moves them into `outDir` only when all of them succeed. */
+export async function commitOutputs(outDir, build) {
+    mkdirSync(outDir, { recursive: true });
+    const stage = mkdtempSync(join(outDir, ".synopkgland-build-"));
+    try {
+        return (await build(stage)).map((staged) => {
+            const output = join(outDir, basename(staged));
+            renameSync(staged, output);
+            return output;
+        });
+    }
+    finally {
+        rmSync(stage, { recursive: true, force: true });
+    }
+}

package/dist/standalone/build.d.ts

@@ -4,11 +4,14 @@ export interface CommandResult {
     stderr: string;
     /** The program itself was not found. */
     missing?: boolean;
+    /** Standard output, when the caller asked to capture it. */
+    stdout?: string;
 }
 export type CommandRunner = (command: string, args: string[], options: {
     cwd: string;
     env: Record<string, string | undefined>;
-}) => CommandResult;
+    capture?: boolean;
+}) => CommandResult | Promise<CommandResult>;
 export interface StandaloneBuildOptions {
     root: string;
     /** Defaults to every arch in the manifest. */
@@ -17,11 +20,18 @@ export interface StandaloneBuildOptions {
     outDir?: string;
     /** INFO os_min_ver for every SPK (a release such as 7.1, or a full 7.x-build); defaults to the manifest's. */
     minDsm?: string;
+    /** Architectures built at once; defaults to 1. */
+    jobs?: number;
     run?: CommandRunner;
 }
-/** Argv only, never a shell; output streams to the terminal except stderr, which is also kept. */
+/** Argv only, never a shell; output streams to the terminal except stderr, which is also kept, and captured stdout. */
 export declare const runCommand: CommandRunner;
+/** `runCommand` for concurrent builds: every output line goes to stderr behind `prefix`, so architectures stay apart. */
+export declare function prefixedRunner(prefix: string): CommandRunner;
+/** The runner one architecture uses: the caller's, or a labelled one while several architectures share the terminal. */
+export declare function runnerFor(run: CommandRunner | undefined, jobs: number, arch: string): CommandRunner;
 /** `build` for a Standalone Package: build the UI, compile the CGI, pack one SPK per arch. */
 export declare function buildStandalone(options: StandaloneBuildOptions): Promise<{
     outputs: string[];
+    warnings: string[];
 }>;