@synopackageland/cli 0.7.2 → 0.8.0

package/dist/spk/dsm-spec.js

@@ -0,0 +1,86 @@
+import DSM_PLATFORMS from "../build-spk/dsm-platforms.json" with { type: "json" };
+/**
+ * The parts of the Synology DSM 7 Developer Guide that `inspect` checks
+ * against, transcribed from the guide's INFO, Package Structure and
+ * Appendix A pages.
+ */
+/** INFO Necessary Fields. */
+export const REQUIRED_INFO_FIELDS = ["package", "version", "os_min_ver", "description", "arch", "maintainer"];
+/** INFO Optional Fields, without the `displayname_<lang>` and `description_<lang>` families. */
+export const OPTIONAL_INFO_FIELDS = [
+    "displayname", "maintainer_url", "distributor", "distributor_url", "support_url", "support_center", "model",
+    "exclude_arch", "checksum", "adminport", "adminurl", "adminprotocol", "dsmuidir", "dsmappname", "dsmapppage",
+    "dsmapplaunchname", "checkport", "startable", "ctl_stop", "ctl_uninstall", "precheckstartstop", "helpurl", "beta",
+    "report_url", "install_reboot", "install_dep_packages", "install_conflict_packages", "install_break_packages",
+    "install_replace_packages", "install_dep_services", "start_dep_services", "extractsize", "support_conf_folder",
+    "install_type", "silent_install", "silent_upgrade", "silent_uninstall", "auto_upgrade_from", "offline_install",
+    "thirdparty", "os_max_ver", "support_move", "exclude_model", "use_deprecated_replace_mechanism",
+    "install_on_cold_storage",
+];
+/**
+ * Fields outside the guide's list that are still expected: `changelog` is
+ * shown by Package Center and used by first-party packages; the others are
+ * written by this SDK and ignored by DSM.
+ */
+export const EXTRA_INFO_FIELDS = ["changelog", "synopkgland_executor_sha256", "spk_land_metadata"];
+/** Optional fields whose value is "yes" or "no". */
+export const BOOLEAN_INFO_FIELDS = [
+    "support_center", "checkport", "startable", "ctl_stop", "ctl_uninstall", "precheckstartstop", "beta",
+    "install_reboot", "support_conf_folder", "silent_install", "silent_upgrade", "silent_uninstall", "offline_install",
+    "thirdparty", "support_move", "use_deprecated_replace_mechanism", "install_on_cold_storage",
+];
+/** Language codes of `displayname_<lang>` and `description_<lang>`. */
+export const INFO_LANGUAGES = [
+    "enu", "cht", "chs", "krn", "ger", "fre", "ita", "spn", "jpn", "dan", "nor", "sve", "nld", "rus", "plk", "ptb",
+    "ptg", "hun", "trk", "csy",
+];
+/** After DSM 7.0, os_min_ver "should be at least 7.0-40000". */
+export const DSM7_MIN_VER = "7.0-40000";
+/**
+ * Appendix A arch families and platforms, with the ELF e_machine their
+ * binaries use, plus DSM 7 platforms newer than the appendix (from
+ * dsm-platforms.json, shared with package-source).
+ */
+const EM_386 = 3, EM_ARM = 40, EM_X86_64 = 62, EM_AARCH64 = 183;
+const APPENDIX_ARCHES = {
+    noarch: undefined, x86_64: EM_X86_64, i686: EM_386, armv7: EM_ARM, armv5: EM_ARM, armv8: EM_AARCH64,
+    evansport: EM_386, "628x": EM_ARM,
+    alpine: EM_ARM, alpine4k: EM_ARM, armada370: EM_ARM, armada375: EM_ARM, armada38x: EM_ARM, armadaxp: EM_ARM,
+    comcerto2k: EM_ARM, monaco: EM_ARM,
+    armada37xx: EM_AARCH64, rtd1296: EM_AARCH64, rtd1619: EM_AARCH64, rtd1619b: EM_AARCH64,
+    apollolake: EM_X86_64, avoton: EM_X86_64, braswell: EM_X86_64, broadwell: EM_X86_64, broadwellnk: EM_X86_64,
+    broadwellntb: EM_X86_64, broadwellntbap: EM_X86_64, bromolow: EM_X86_64, cedarview: EM_X86_64,
+    coffeelake: EM_X86_64, denverton: EM_X86_64, geminilake: EM_X86_64, grantley: EM_X86_64, kvmx64: EM_X86_64,
+    purley: EM_X86_64, skylaked: EM_X86_64, v1000: EM_X86_64,
+};
+const FAMILY_MACHINE = { x86_64: EM_X86_64, aarch64: EM_AARCH64, armv7: EM_ARM };
+export const ARCH_ELF_MACHINE = new Map([
+    ...Object.entries(APPENDIX_ARCHES),
+    ...Object.entries(DSM_PLATFORMS).flatMap(([family, { members, platformOnly }]) => [...members, ...platformOnly].map((platform) => [platform, FAMILY_MACHINE[family]])),
+]);
+/**
+ * Top-level SPK entries of the Package Structure page, plus metadata this SDK
+ * adds; container SPKs also carry a top-level copy of conf/privilege.
+ */
+export const KNOWN_TOP_LEVEL = [
+    "INFO", "package.tgz", "scripts", "conf", "WIZARD_UIFILES", "LICENSE", "PACKAGE_ICON.PNG", "PACKAGE_ICON_256.PNG",
+    "syno_signature.asc", "sdk-package.json", "native-layout.json", "privilege",
+];
+/** scripts/ of the Package Structure page; DSM needs start-stop-status to start, stop and poll a package. */
+export const LIFECYCLE_SCRIPTS = ["preinst", "postinst", "preuninst", "postuninst", "preupgrade", "postupgrade", "start-stop-status"];
+/** Optional scripts, run only with install_replace_packages. */
+export const REPLACE_SCRIPTS = ["prereplace", "postreplace"];
+/** conf/ entries: the conf page's files, and the systemd unit folder of the systemd-user-unit worker. */
+export const CONF_ENTRIES = ["privilege", "resource", "PKG_DEPS", "PKG_CONX", "systemd"];
+/**
+ * Resource ids of the guide's Available Workers pages; `systemd-unit` is not
+ * documented there but is used by packages that install on DSM 7.
+ */
+export const RESOURCE_WORKERS = [
+    "port-config", "usr-local-linker", "data-share", "systemd-user-unit", "systemd-unit", "web-config", "webservice",
+    "docker-project", "docker", "apache22", "indexdb", "mariadb10", "php", "syslog-config", "sysnotify",
+];
+/** PACKAGE_ICON.PNG is 64×64 on DSM 7; PACKAGE_ICON_256.PNG is 256×256. */
+export const PACKAGE_ICONS = [["PACKAGE_ICON.PNG", 64], ["PACKAGE_ICON_256.PNG", 256]];
+/** LICENSE "must be less than 1 MB". */
+export const MAX_LICENSE_BYTES = 1024 * 1024;

package/dist/spk/findings.d.ts

@@ -0,0 +1,13 @@
+import { type SpkRuleCode, type SpkRuleSeverity } from "./rules.js";
+export interface SpkFinding {
+    code: SpkRuleCode;
+    severity: SpkRuleSeverity;
+    /** The SPK entry the finding is about, when there is one. */
+    path?: string;
+    message: string;
+}
+/** Collects findings; each code's severity comes from its rule. */
+export declare class Findings {
+    readonly list: SpkFinding[];
+    add(code: SpkRuleCode, message: string, path?: string): void;
+}

package/dist/spk/findings.js

@@ -0,0 +1,8 @@
+import { SPK_RULES } from "./rules.js";
+/** Collects findings; each code's severity comes from its rule. */
+export class Findings {
+    list = [];
+    add(code, message, path) {
+        this.list.push({ code, severity: SPK_RULES[code].severity, ...(path ? { path } : {}), message });
+    }
+}

package/dist/spk/inspect.d.ts

@@ -0,0 +1,18 @@
+import { type SpkInspection } from "../standalone/inspect-spk.js";
+import { type SpkFinding } from "./validate-spk.js";
+export interface SpkReport extends SpkInspection {
+    /** Built by synopkgland, so its build contract (`findings`) was checked too. */
+    synopkgland: boolean;
+    /** The DSM 7 package format rules, checked on every SPK. */
+    dsm: {
+        ok: boolean;
+        errors: SpkFinding[];
+        warnings: SpkFinding[];
+    };
+}
+/**
+ * Checks any SPK against the DSM 7 package format. An SPK that carries a
+ * synopkgland build marker is also checked against the build contract;
+ * others are never held to it.
+ */
+export declare function inspectAnySpk(spkPath: string): Promise<SpkReport>;

package/dist/spk/inspect.js

@@ -0,0 +1,62 @@
+import { createWriteStream, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { finished } from "node:stream/promises";
+import * as tar from "tar";
+import { inspectSpk, listPayload } from "../standalone/inspect-spk.js";
+import { validateSpk } from "./validate-spk.js";
+/** Top-level files the native-go/binary and native layout builds write; no DSM file has these names. */
+const BUILD_MARKERS = ["sdk-package.json", "native-layout.json"];
+/** A container build ships its manifest in the payload. */
+const CONTAINER_MARKER = "synology-app.yaml";
+/**
+ * Checks any SPK against the DSM 7 package format. An SPK that carries a
+ * synopkgland build marker is also checked against the build contract;
+ * others are never held to it.
+ */
+export async function inspectAnySpk(spkPath) {
+    const validation = await validateSpk(spkPath);
+    const dsm = { ok: validation.ok, errors: validation.errors, warnings: validation.warnings };
+    const facts = await readFacts(spkPath);
+    if (BUILD_MARKERS.some((name) => facts.top.has(name)) || facts.payload.some((entry) => entry.path === CONTAINER_MARKER)) {
+        return { ...(await inspectSpk(spkPath)), synopkgland: true, dsm };
+    }
+    return {
+        ...(validation.package ? { package: validation.package } : {}),
+        ...(validation.version ? { version: validation.version } : {}),
+        ...(validation.arch ? { arch: validation.arch } : {}),
+        signed: facts.top.has("syno_signature.asc"),
+        payload: facts.payload,
+        findings: [],
+        capabilities: [],
+        synopkgland: false,
+        dsm,
+    };
+}
+/** Top-level names and the payload listing; an unreadable archive yields none, which the DSM rules already report. */
+async function readFacts(spkPath) {
+    const facts = { top: new Set(), payload: [] };
+    const dir = mkdtempSync(join(tmpdir(), "syno-inspect-facts-"));
+    try {
+        const writes = [];
+        await tar.t({
+            file: spkPath,
+            onReadEntry: (entry) => {
+                const path = entry.path.replace(/^\.\//, "");
+                facts.top.add(path.split("/")[0]);
+                if (path === "package.tgz" && entry.type === "File")
+                    writes.push(finished(entry.pipe(createWriteStream(join(dir, "package.tgz")))));
+            },
+        });
+        await Promise.all(writes);
+        if (writes.length)
+            facts.payload = await listPayload(join(dir, "package.tgz"), []);
+    }
+    catch {
+        // Not a readable tar or tar.gz.
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    return facts;
+}

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