@synopackageland/cli 0.7.3 → 0.9.0

package/dist/spk/check-info.js

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { ARCH_ELF_MACHINE, BOOLEAN_INFO_FIELDS, DSM7_MIN_VER, EXTRA_INFO_FIELDS, INFO_LANGUAGES, OPTIONAL_INFO_FIELDS, REQUIRED_INFO_FIELDS, } from "./dsm-spec.js";
+const KNOWN_FIELDS = new Set([...REQUIRED_INFO_FIELDS, ...OPTIONAL_INFO_FIELDS, ...EXTRA_INFO_FIELDS]);
+const BOOLEAN_FIELDS = new Set(BOOLEAN_INFO_FIELDS);
+const LANGUAGES = new Set(INFO_LANGUAGES);
+const MAX_VERSION_PART = 2 ** 31 - 1;
+/** X.Y-B as the guide states, and X.Y.Z-B as DSM itself reports (7.2.1-69057). */
+const OS_VER = /^(\d+)\.(\d+)(?:\.(\d+))?-(\d+)$/;
+/** INFO lines are `key="value"` (or unquoted `key=value`); quotes may escape `\"` and `\\`. */
+export function parseInfo(text, findings) {
+    const fields = new Map();
+    text.split(/\r?\n/).forEach((line, index) => {
+        if (/^\s*(#.*)?$/.test(line))
+            return;
+        const match = /^([A-Za-z0-9_]+)=(.*)$/.exec(line);
+        if (!match) {
+            findings?.add("SPK_INFO_LINE_INVALID", `INFO 第 ${index + 1} 行不是 key="value"：${line.slice(0, 60)}`, "INFO");
+            return;
+        }
+        const [, key, raw] = match;
+        let value = raw;
+        if (raw.startsWith('"')) {
+            const quoted = /^"((?:[^"\\]|\\.)*)"\s*$/.exec(raw);
+            if (!quoted) {
+                findings?.add("SPK_INFO_VALUE_UNTERMINATED", `INFO 第 ${index + 1} 行 ${key} 的引號沒有結束。`, "INFO");
+                return;
+            }
+            value = quoted[1].replace(/\\(.)/g, "$1");
+        }
+        if (fields.has(key))
+            findings?.add("SPK_INFO_FIELD_DUPLICATE", `INFO 重複設定 ${key}；只有一個值會生效。`, "INFO");
+        fields.set(key, value);
+    });
+    return fields;
+}
+function compareOsVer(a, b) {
+    const parse = (value) => { const m = OS_VER.exec(value); return [Number(m[1]), Number(m[2]), Number(m[3] ?? 0), Number(m[4])]; };
+    const [x, y] = [parse(a), parse(b)];
+    for (let i = 0; i < 4; i++)
+        if (x[i] !== y[i])
+            return x[i] - y[i];
+    return 0;
+}
+function checkVersion(version, findings) {
+    const parts = version.split(/[._-]/);
+    if (parts.some((part) => !/^\d+$/.test(part) || Number(part) > MAX_VERSION_PART)) {
+        findings.add("SPK_INFO_VERSION_INVALID", `INFO version「${version}」只能是以 .、-、_ 分隔的數字（每段 0–2147483647），例如 1.2.3-0001。`, "INFO");
+    }
+    else if (!version.includes("-")) {
+        findings.add("SPK_INFO_VERSION_NO_BUILD", `INFO version「${version}」沒有 -<build> 編號；指南格式為 [feature number]-[build number]，例如 ${version}-0001。`, "INFO");
+    }
+}
+function checkArch(field, value, findings) {
+    const tokens = value.split(/\s+/).filter(Boolean);
+    for (const token of tokens.filter((t) => !ARCH_ELF_MACHINE.has(t))) {
+        findings.add("SPK_INFO_ARCH_UNKNOWN", `INFO ${field} 含有指南 Appendix A 與已知 DSM 7 平台都沒有的值「${token}」。`, "INFO");
+    }
+    if (field === "arch" && tokens.includes("noarch") && tokens.length > 1) {
+        findings.add("SPK_INFO_ARCH_NOARCH_MIXED", `INFO arch「${value}」同時有 noarch 與其他值；noarch 已代表所有平台。`, "INFO");
+    }
+}
+function checkTranslations(key, findings) {
+    const match = /^(displayname|description)_(.+)$/.exec(key);
+    if (!match)
+        return false;
+    if (!LANGUAGES.has(match[2])) {
+        findings.add("SPK_INFO_LANG_UNKNOWN", `INFO ${key} 的語言碼「${match[2]}」不在指南的清單（${INFO_LANGUAGES.join("、")}）。`, "INFO");
+    }
+    return true;
+}
+/** Checks INFO fields; `payloadPath` is package.tgz on disk, for the checksum. */
+export function checkInfoFields(fields, payloadPath, findings) {
+    for (const key of REQUIRED_INFO_FIELDS) {
+        if (!fields.get(key))
+            findings.add("SPK_INFO_FIELD_REQUIRED", `INFO 缺少必填欄位 ${key}。`, "INFO");
+    }
+    if (!fields.get("displayname")) {
+        findings.add("SPK_INFO_DISPLAYNAME_MISSING", "INFO 沒有 displayname；Package Center 會顯示 package 值。", "INFO");
+    }
+    const pkg = fields.get("package");
+    if (pkg && /[:/><|=]/.test(pkg)) {
+        findings.add("SPK_INFO_PACKAGE_INVALID", `INFO package「${pkg}」不能含有 : / > < | =。`, "INFO");
+    }
+    const version = fields.get("version");
+    if (version)
+        checkVersion(version, findings);
+    for (const key of ["os_min_ver", "os_max_ver"]) {
+        const value = fields.get(key);
+        if (!value)
+            continue;
+        if (!OS_VER.test(value)) {
+            findings.add("SPK_INFO_OS_VER_INVALID", `INFO ${key}「${value}」不是 <major>.<minor>-<build>（例如 7.0-40000）。`, "INFO");
+        }
+        else if (key === "os_min_ver" && compareOsVer(value, DSM7_MIN_VER) < 0) {
+            findings.add("SPK_INFO_OS_MIN_VER_LOW", `INFO os_min_ver「${value}」低於 ${DSM7_MIN_VER}；DSM 7 套件應至少為 ${DSM7_MIN_VER}。`, "INFO");
+        }
+    }
+    for (const key of ["arch", "exclude_arch"]) {
+        const value = fields.get(key);
+        if (value)
+            checkArch(key, value, findings);
+    }
+    for (const [key, value] of fields) {
+        if (BOOLEAN_FIELDS.has(key) && value !== "yes" && value !== "no") {
+            findings.add("SPK_INFO_BOOLEAN_INVALID", `INFO ${key}「${value}」只能是 "yes" 或 "no"。`, "INFO");
+        }
+        if (!checkTranslations(key, findings) && !KNOWN_FIELDS.has(key)) {
+            findings.add("SPK_INFO_FIELD_UNKNOWN", `INFO ${key} 不是指南列出的欄位；DSM 不會使用它。`, "INFO");
+        }
+    }
+    const adminport = fields.get("adminport");
+    if (adminport !== undefined && (!/^\d+$/.test(adminport) || Number(adminport) > 65536)) {
+        findings.add("SPK_INFO_ADMINPORT_INVALID", `INFO adminport「${adminport}」必須是 0–65536 的整數。`, "INFO");
+    }
+    const checksum = fields.get("checksum");
+    if (checksum && payloadPath) {
+        const actual = createHash("md5").update(readFileSync(payloadPath)).digest("hex");
+        if (checksum.toLowerCase() !== actual) {
+            findings.add("SPK_INFO_CHECKSUM_MISMATCH", `INFO checksum「${checksum}」不是 package.tgz 的 MD5（${actual}）。`, "INFO");
+        }
+    }
+}

package/dist/spk/check-metadata.d.ts

@@ -0,0 +1,7 @@
+import type { Findings } from "./findings.js";
+/** The outer SPK files by exact path, and each entry's mode. */
+export interface OuterFiles {
+    files: Map<string, Buffer>;
+    modes: Map<string, number>;
+}
+export declare function checkMetadata(outer: OuterFiles, findings: Findings): void;

package/dist/spk/check-metadata.js

@@ -0,0 +1,113 @@
+import { CONF_ENTRIES, INFO_LANGUAGES, LIFECYCLE_SCRIPTS, MAX_LICENSE_BYTES, PACKAGE_ICONS, REPLACE_SCRIPTS, RESOURCE_WORKERS, } from "./dsm-spec.js";
+const CONF = new Set(CONF_ENTRIES);
+const WORKERS = new Set(RESOURCE_WORKERS);
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const WIZARD_NAME = new RegExp(`^(install|upgrade|uninstall)_uifile(_(${INFO_LANGUAGES.join("|")}))?(\\.sh)?$`);
+const RUN_AS = ["package", "root"];
+const executable = (mode) => ((mode ?? 0) & 0o111) !== 0;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text?.toString("utf8") ?? "");
+    }
+    catch {
+        return undefined;
+    }
+}
+function checkScripts({ files, modes }, findings) {
+    for (const name of [...LIFECYCLE_SCRIPTS, ...REPLACE_SCRIPTS]) {
+        const path = `scripts/${name}`;
+        const body = files.get(path);
+        if (!body) {
+            if (name === "start-stop-status")
+                findings.add("SPK_SCRIPT_MISSING", `缺少 ${path}；DSM 用它啟動、停止與查詢套件狀態。`, path);
+            else if (LIFECYCLE_SCRIPTS.includes(name))
+                findings.add("SPK_SCRIPT_HOOK_MISSING", `缺少 ${path}；指南把它列為必備，沒有事要做時寫 #!/bin/sh 與 exit 0。`, path);
+            continue;
+        }
+        if (!executable(modes.get(path)))
+            findings.add("SPK_SCRIPT_NOT_EXECUTABLE", `${path} 沒有執行權限（mode ${(modes.get(path) ?? 0).toString(8)}）；打包前 chmod 755。`, path);
+        const head = body.subarray(0, 4).toString("latin1");
+        if (!head.startsWith("#!") && head !== "\x7fELF")
+            findings.add("SPK_SCRIPT_NO_INTERPRETER", `${path} 開頭沒有 #!（例如 #!/bin/sh）。`, path);
+    }
+}
+function checkPrivilege(files, findings) {
+    const path = "conf/privilege";
+    if (!files.has(path)) {
+        findings.add("SPK_PRIVILEGE_MISSING", "缺少 conf/privilege；DSM 7 起每個套件都必須明確宣告執行身分。", path);
+        return;
+    }
+    const privilege = parseJson(files.get(path));
+    const runAs = (value) => (isRecord(value) ? value["run-as"] : undefined);
+    const listed = isRecord(privilege)
+        ? ["ctrl-script", "executable"].flatMap((key) => (Array.isArray(privilege[key]) ? privilege[key] : []).map(runAs))
+        : [];
+    const values = isRecord(privilege) ? [runAs(privilege.defaults), ...listed] : [];
+    if (!isRecord(privilege) || values.some((value) => typeof value !== "string" || !RUN_AS.includes(value))) {
+        findings.add("SPK_PRIVILEGE_INVALID", 'conf/privilege 必須是 JSON 物件，有 defaults.run-as，且每個 run-as 是 "package" 或 "root"。', path);
+        return;
+    }
+    if (values.includes("root"))
+        findings.add("SPK_PRIVILEGE_ROOT", "conf/privilege 要求以 root 執行；DSM 7 第三方套件應以 package 帳號執行。", path);
+}
+function checkConf({ files, modes }, findings) {
+    checkPrivilege(files, findings);
+    const resourcePath = "conf/resource";
+    if (files.has(resourcePath)) {
+        const resource = parseJson(files.get(resourcePath));
+        if (!isRecord(resource))
+            findings.add("SPK_RESOURCE_INVALID", "conf/resource 不是 JSON 物件。", resourcePath);
+        else
+            for (const id of Object.keys(resource).filter((key) => !WORKERS.has(key))) {
+                findings.add("SPK_RESOURCE_UNKNOWN", `conf/resource 的「${id}」不是指南列出的 resource worker。`, resourcePath);
+            }
+    }
+    const names = new Set([...modes.keys()].filter((path) => path.startsWith("conf/")).map((path) => path.split("/")[1]).filter(Boolean));
+    for (const name of [...names].filter((n) => !CONF.has(n)))
+        findings.add("SPK_CONF_UNKNOWN", `conf/${name} 不是 DSM 讀取的設定檔。`, `conf/${name}`);
+}
+function checkIcons(files, findings) {
+    for (const [name, size] of PACKAGE_ICONS) {
+        const png = files.get(name);
+        if (!png) {
+            findings.add("SPK_ICON_MISSING", `缺少 ${name}（${size}×${size} PNG）。`, name);
+        }
+        else if (png.length < 24 || !png.subarray(0, 8).equals(PNG_SIGNATURE) || png.toString("latin1", 12, 16) !== "IHDR") {
+            findings.add("SPK_ICON_INVALID", `${name} 不是 PNG。`, name);
+        }
+        else if (png.readUInt32BE(16) !== size || png.readUInt32BE(20) !== size) {
+            findings.add("SPK_ICON_SIZE", `${name} 是 ${png.readUInt32BE(16)}×${png.readUInt32BE(20)}，指南要求 ${size}×${size}。`, name);
+        }
+    }
+}
+function checkWizards({ files, modes }, findings) {
+    for (const path of [...modes.keys()].filter((p) => p.startsWith("WIZARD_UIFILES/") && files.has(p))) {
+        const name = path.slice("WIZARD_UIFILES/".length);
+        if (!WIZARD_NAME.test(name)) {
+            findings.add("SPK_WIZARD_UNKNOWN", `${path} 不是 install／upgrade／uninstall_uifile[_<lang>][.sh]；DSM 不會讀它。`, path);
+        }
+        else if (name.endsWith(".sh")) {
+            if (!executable(modes.get(path)))
+                findings.add("SPK_WIZARD_SCRIPT_NOT_EXECUTABLE", `${path} 沒有執行權限；DSM 執行它來產生精靈。`, path);
+        }
+        else if (!Array.isArray(parseJson(files.get(path)))) {
+            findings.add("SPK_WIZARD_INVALID", `${path} 不是 JSON 陣列（每個元素是一個精靈步驟）。`, path);
+        }
+    }
+}
+export function checkMetadata(outer, findings) {
+    checkScripts(outer, findings);
+    checkConf(outer, findings);
+    checkIcons(outer.files, findings);
+    checkWizards(outer, findings);
+    const license = outer.files.get("LICENSE");
+    if (license && license.length >= MAX_LICENSE_BYTES)
+        findings.add("SPK_LICENSE_TOO_LARGE", `LICENSE 有 ${license.length} bytes；指南要求小於 1 MB。`, "LICENSE");
+    const signature = outer.files.get("syno_signature.asc");
+    if (signature && !signature.toString("latin1").includes("-----BEGIN PGP SIGNATURE-----")) {
+        findings.add("SPK_SIGNATURE_INVALID", "syno_signature.asc 不是 ASCII-armored PGP 簽章。", "syno_signature.asc");
+    }
+}

package/dist/spk/check-payload.d.ts

@@ -0,0 +1,2 @@
+import type { Findings } from "./findings.js";
+export declare function checkPayload(payloadPath: string, info: Record<string, string>, findings: Findings): Promise<void>;

package/dist/spk/check-payload.js

@@ -0,0 +1,156 @@
+import { openSync, readSync, closeSync } from "node:fs";
+import { posix } from "node:path";
+import * as tar from "tar";
+import { ARCH_ELF_MACHINE } from "./dsm-spec.js";
+const XZ_MAGIC = Buffer.from([0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00]);
+const ELF_MAGIC = Buffer.from("\x7fELF", "latin1");
+const MAX_TEXT = 1024 * 1024;
+const HEAD_BYTES = 20;
+/** `section:key`: a DSM string reference rather than literal text. */
+const STRING_REF = /^([A-Za-z0-9_]+):([A-Za-z0-9_]+)$/;
+const at = (path) => `package.tgz:${path}`;
+function startsWith(file, magic) {
+    const fd = openSync(file, "r");
+    try {
+        const head = Buffer.alloc(magic.length);
+        return readSync(fd, head, 0, magic.length, 0) === magic.length && head.equals(magic);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** `dsmuidir` is one path, or since DSM 7.0-40731 several `name:path` pairs. */
+function uiDirs(dsmuidir) {
+    return (dsmuidir ?? "").split(/\s+/).filter(Boolean).map((item) => posix.normalize(item.slice(item.indexOf(":") + 1)).replace(/\/$/, ""));
+}
+/** Lists package.tgz without extracting it, keeping only file heads and the few texts the rules read. */
+async function scanPayload(payloadPath, wanted, findings) {
+    const files = [];
+    let entries = 0;
+    try {
+        await tar.t({
+            file: payloadPath,
+            strict: true,
+            onReadEntry: (entry) => {
+                entries++;
+                const path = entry.path.replace(/^\.\//, "");
+                checkEntryPath(path, entry.type, entry.linkpath, findings);
+                if (entry.type !== "File")
+                    return;
+                const file = { path, head: Buffer.alloc(0) };
+                const keep = wanted(path) && (entry.size ?? 0) <= MAX_TEXT;
+                const chunks = [];
+                entry.on("data", (chunk) => {
+                    if (file.head.length < HEAD_BYTES)
+                        file.head = Buffer.concat([file.head, chunk]).subarray(0, HEAD_BYTES);
+                    if (keep)
+                        chunks.push(chunk);
+                });
+                entry.on("end", () => { if (keep)
+                    file.text = Buffer.concat(chunks).toString("utf8"); });
+                files.push(file);
+            },
+        });
+    }
+    catch {
+        entries = 0;
+    }
+    if (entries === 0) {
+        findings.add("SPK_PAYLOAD_UNREADABLE", "package.tgz 不是可讀的 tar、tar.gz 封存，或是空的。", "package.tgz");
+        return undefined;
+    }
+    return files;
+}
+function checkEntryPath(path, type, linkpath, findings) {
+    if (path.startsWith("/") || posix.normalize(path).split("/")[0] === "..") {
+        findings.add("SPK_PAYLOAD_PATH_UNSAFE", `${path} 會解開到套件目錄之外。`, at(path));
+        return;
+    }
+    if (type === "SymbolicLink" && linkpath) {
+        if (linkpath.startsWith("/")) {
+            findings.add("SPK_PAYLOAD_LINK_ABSOLUTE", `${path} 是指向 ${linkpath} 的絕對路徑 symlink；目標由 NAS 決定，不在套件內。`, at(path));
+        }
+        else if (posix.normalize(posix.join(posix.dirname(path), linkpath)).split("/")[0] === "..") {
+            findings.add("SPK_PAYLOAD_LINK_ESCAPE", `${path} 的 symlink 目標 ${linkpath} 跳出套件目錄。`, at(path));
+        }
+    }
+    if (type === "Link" && linkpath && (linkpath.startsWith("/") || posix.normalize(linkpath).split("/")[0] === "..")) {
+        findings.add("SPK_PAYLOAD_LINK_ESCAPE", `${path} 的 hard link 目標 ${linkpath} 不在套件內。`, at(path));
+    }
+}
+/** Sections the package defines itself in its `texts/<lang>/strings` files. */
+function ownSections(files) {
+    const sections = new Set();
+    for (const file of files) {
+        if (!/(^|\/)texts\/[^/]+\/strings$/.test(file.path) || file.text === undefined)
+            continue;
+        for (const match of file.text.matchAll(/^\s*\[([^\]]+)\]\s*$/gm))
+            sections.add(match[1]);
+    }
+    return sections;
+}
+/**
+ * DSM resolves a `section:key` title only from the strings of an entry that
+ * declares `texts`; without it the menu shows the raw key. DSM's own
+ * sections need no `texts`, so only the package's own sections are errors.
+ */
+function checkUiConfig(file, sections, findings) {
+    let config;
+    try {
+        config = JSON.parse(file.text ?? "");
+    }
+    catch { /* reported below */ }
+    if (typeof config !== "object" || config === null || Array.isArray(config)) {
+        findings.add("SPK_UI_CONFIG_INVALID", `${file.path} 不是 JSON 物件。`, at(file.path));
+        return;
+    }
+    for (const group of Object.values(config)) {
+        if (typeof group !== "object" || group === null)
+            continue;
+        for (const [id, entry] of Object.entries(group)) {
+            if (typeof entry !== "object" || entry === null || "texts" in entry)
+                continue;
+            for (const field of ["title", "desc"]) {
+                const value = entry[field];
+                const ref = typeof value === "string" ? STRING_REF.exec(value) : null;
+                if (!ref)
+                    continue;
+                const own = ref[1] === "synopkgland" || sections.has(ref[1]);
+                findings.add(own ? "SPK_UI_TEXTS_MISSING" : "SPK_UI_TEXTS_UNDECLARED", `${file.path} 的 ${id}.${field}「${value}」是字串參照，但這個 entry 沒有宣告 "texts"；${own ? "DSM 會直接顯示這個 key" : "除非是 DSM 內建的 section，否則 DSM 會直接顯示這個 key"}。`, at(file.path));
+            }
+        }
+    }
+}
+/** ELF files must run on the platforms INFO arch names; a noarch package carries none. */
+function checkElf(files, arch, findings) {
+    const tokens = (arch ?? "").split(/\s+/).filter(Boolean);
+    const noarch = tokens.length === 1 && tokens[0] === "noarch";
+    const machines = new Set(tokens.map((token) => ARCH_ELF_MACHINE.get(token)));
+    const checkable = !noarch && tokens.length > 0 && tokens.every((token) => ARCH_ELF_MACHINE.get(token) !== undefined);
+    for (const file of files) {
+        if (file.head.length < HEAD_BYTES || !file.head.subarray(0, 4).equals(ELF_MAGIC))
+            continue;
+        const machine = file.head[5] === 2 ? file.head.readUInt16BE(18) : file.head.readUInt16LE(18);
+        if (noarch) {
+            findings.add("SPK_NOARCH_ELF", `${file.path} 是 ELF 執行檔，但 INFO arch 是 noarch；noarch 套件只能有腳本，否則在其他 CPU 的 NAS 上無法執行。`, at(file.path));
+        }
+        else if (checkable && !machines.has(machine)) {
+            findings.add("SPK_ELF_ARCH_MISMATCH", `${file.path} 的 ELF machine 是 ${machine}，與 INFO arch「${arch}」的 CPU 不符。`, at(file.path));
+        }
+    }
+}
+export async function checkPayload(payloadPath, info, findings) {
+    if (startsWith(payloadPath, XZ_MAGIC)) {
+        findings.add("SPK_PAYLOAD_XZ", "package.tgz 是 xz 壓縮（Synology toolkit 的格式）；inspect 讀不了 xz，沒有檢查 payload 內容。", "package.tgz");
+        return;
+    }
+    const dirs = uiDirs(info.dsmuidir);
+    const configs = new Set(dirs.map((dir) => posix.join(dir, "config")));
+    const files = await scanPayload(payloadPath, (path) => configs.has(path) || (/\/texts\/[^/]+\/strings$/.test(path) && dirs.some((dir) => path.startsWith(`${dir}/`))), findings);
+    if (!files)
+        return;
+    const sections = ownSections(files);
+    for (const file of files.filter((f) => configs.has(f.path)))
+        checkUiConfig(file, sections, findings);
+    checkElf(files, info.arch, findings);
+}

package/dist/spk/dsm-spec.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 declare const REQUIRED_INFO_FIELDS: readonly ["package", "version", "os_min_ver", "description", "arch", "maintainer"];
+/** INFO Optional Fields, without the `displayname_<lang>` and `description_<lang>` families. */
+export declare const OPTIONAL_INFO_FIELDS: readonly ["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 declare const EXTRA_INFO_FIELDS: readonly ["changelog", "synopkgland_executor_sha256", "spk_land_metadata"];
+/** Optional fields whose value is "yes" or "no". */
+export declare const BOOLEAN_INFO_FIELDS: readonly ["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 declare const INFO_LANGUAGES: readonly ["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 declare const DSM7_MIN_VER = "7.0-40000";
+export declare const ARCH_ELF_MACHINE: ReadonlyMap<string, number | undefined>;
+/**
+ * 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 declare const KNOWN_TOP_LEVEL: readonly ["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 declare const LIFECYCLE_SCRIPTS: readonly ["preinst", "postinst", "preuninst", "postuninst", "preupgrade", "postupgrade", "start-stop-status"];
+/** Optional scripts, run only with install_replace_packages. */
+export declare const REPLACE_SCRIPTS: readonly ["prereplace", "postreplace"];
+/** conf/ entries: the conf page's files, and the systemd unit folder of the systemd-user-unit worker. */
+export declare const CONF_ENTRIES: readonly ["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 declare const RESOURCE_WORKERS: readonly ["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 declare const PACKAGE_ICONS: readonly [readonly ["PACKAGE_ICON.PNG", 64], readonly ["PACKAGE_ICON_256.PNG", 256]];
+/** LICENSE "must be less than 1 MB". */
+export declare const MAX_LICENSE_BYTES: number;

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