@synopackageland/cli 0.7.3 → 0.8.0

package/dist/reproducible.js

@@ -0,0 +1,121 @@
+/**
+ * `build --verify-reproducible`: build once more from a clean state and compare
+ * the SPKs. Projects may declare the dependency files whose fingerprint decides
+ * when the check needs to run again; the last passing one is recorded.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { extractSpk, walkFiles } from "./build-spk/generator.js";
+import { invalid, readReproducible } from "./reproducible-config.js";
+export { readReproducible, validateReproducible } from "./reproducible-config.js";
+export const FINGERPRINT_RECORD = "reproducible-fingerprint.json";
+const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function insideProject(root, path) {
+    const rel = relative(realpathSync(root), realpathSync(path));
+    return rel !== ".." && !rel.startsWith("../") && !isAbsolute(rel);
+}
+/** SHA-256 of each declared input plus the CLI version and `extra` pins, and one digest over all of them. */
+export function dependencyFingerprint(root, config, extra = {}) {
+    const digests = { synopkgland: CLI_VERSION, ...extra };
+    for (const path of config.inputs) {
+        const full = join(root, path);
+        if (!existsSync(full) || !lstatSync(full).isFile() || !insideProject(root, full))
+            invalid(`reproducible input ${path} is not a regular file in the project.`);
+        digests[path] = sha256(readFileSync(full));
+    }
+    const inputs = Object.fromEntries(Object.entries(digests).sort(([a], [b]) => a.localeCompare(b)));
+    return { fingerprint: sha256(JSON.stringify(inputs)), inputs };
+}
+function readRecord(path) {
+    try {
+        const record = JSON.parse(readFileSync(path, "utf8"));
+        return typeof record.fingerprint === "string" && record.inputs && Array.isArray(record.arches) ? record : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function cleanPaths(root, clean, arches) {
+    for (const pattern of clean) {
+        for (const path of new Set(arches.length ? arches.map((arch) => pattern.replaceAll("{arch}", arch)) : [pattern])) {
+            const full = resolve(root, path);
+            if (!existsSync(dirname(full)) || !insideProject(root, dirname(full)))
+                continue;
+            rmSync(full, { recursive: true, force: true });
+        }
+    }
+}
+function fileDigests(dir) {
+    return new Map(walkFiles(dir).map((file) => [file, sha256(readFileSync(join(dir, file)))]));
+}
+async function compareSpks(first, second) {
+    const digests = [sha256(readFileSync(first)), sha256(readFileSync(second))];
+    const result = { output: first, identical: digests[0] === digests[1], sha256: digests, payload: [], metadata: [] };
+    if (result.identical)
+        return result;
+    const work = mkdtempSync(join(tmpdir(), "synopkgland-compare-"));
+    try {
+        const [a, b] = [join(work, "1"), join(work, "2")];
+        await extractSpk(first, a);
+        await extractSpk(second, b);
+        const [left, right] = [fileDigests(a), fileDigests(b)];
+        for (const file of [...new Set([...left.keys(), ...right.keys()])].sort()) {
+            if (left.get(file) === right.get(file) || file === "package.tgz")
+                continue;
+            if (file.startsWith("package/"))
+                result.payload.push(file.slice("package/".length));
+            else
+                result.metadata.push(file);
+        }
+        return result;
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}
+/**
+ * Builds the project again with `rebuild` into a temporary folder, after removing
+ * the declared `clean` paths and with an empty GOCACHE, and compares each SPK with
+ * `outputs`, the SPKs of this build. With declared inputs, mode `changed` skips
+ * while the fingerprint and architectures match the last passing record, and a
+ * passing check updates that record.
+ */
+export async function checkReproducible(options) {
+    const { root, outputs, arches } = options;
+    const config = readReproducible(options.manifestPath);
+    const recordPath = join(root, FINGERPRINT_RECORD);
+    const current = config.inputs.length ? dependencyFingerprint(root, config, options.extraInputs) : undefined;
+    const recorded = current && readRecord(recordPath);
+    const changed = current && Object.keys({ ...current.inputs, ...recorded?.inputs }).filter((key) => current.inputs[key] !== recorded?.inputs[key]).sort();
+    if (current && options.mode === "changed" && recorded?.fingerprint === current.fingerprint && arches.every((arch) => recorded.arches.includes(arch))) {
+        return { skipped: true, identical: true, fingerprint: current.fingerprint, changed, results: [] };
+    }
+    cleanPaths(root, config.clean, arches);
+    const outDir = mkdtempSync(join(tmpdir(), "synopkgland-reproducible-"));
+    const gocache = mkdtempSync(join(tmpdir(), "synopkgland-gocache-"));
+    const saved = process.env.GOCACHE;
+    process.env.GOCACHE = gocache;
+    try {
+        const second = await options.rebuild(outDir);
+        const results = [];
+        for (const [index, output] of outputs.entries())
+            results.push(await compareSpks(output, second[index]));
+        const identical = results.length === outputs.length && results.every((result) => result.identical);
+        if (current && identical) {
+            const known = recorded?.fingerprint === current.fingerprint ? recorded.arches : [];
+            writeFileSync(recordPath, `${JSON.stringify({ ...current, arches: [...new Set([...known, ...arches])].sort() }, null, 2)}\n`);
+        }
+        return { skipped: false, identical, ...(current ? { fingerprint: current.fingerprint, changed } : {}), results };
+    }
+    finally {
+        if (saved === undefined)
+            delete process.env.GOCACHE;
+        else
+            process.env.GOCACHE = saved;
+        for (const dir of [outDir, gocache])
+            rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/runtime/executor-build.d.ts

@@ -11,7 +11,7 @@ export interface ExecutorArtifact extends ExecutorPins {
     tasks: ExecutorTask[];
     implementation: 'executor';
 }
-export declare function buildExecutor(m: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner): ExecutorArtifact | undefined;
+export declare function buildExecutor(m: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner): Promise<ExecutorArtifact | undefined>;
 export declare function executorPlan(a: ExecutorArtifact): {
     package: string;
     executorDigest: string;

package/dist/runtime/executor-build.js

@@ -6,7 +6,7 @@ import { StandaloneBuildError } from '../standalone/spk.js';
 import { checkCgiBinary } from '../standalone/binary.js';
 import { executorPolicy, executorPolicyText, sha256 } from './executor-policy.js';
 import { executorTasks } from './executor-tasks.js';
-export function buildExecutor(m, arch, work, run) {
+export async function buildExecutor(m, arch, work, run) {
     if (!m.capabilities.delegate && !m.capabilities.rootOps)
         return undefined;
     const dir = join(work, `executor-${arch}`);
@@ -15,14 +15,14 @@ export function buildExecutor(m, arch, work, run) {
     if (!existsSync(join(source, 'go.mod')))
         throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', 'Executor sources are missing.');
     const binary = join(dir, 'executor');
-    const result = run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', binary, '.'], { cwd: source, env: { ...process.env, ...pinnedGoBuildEnv(arch) } });
+    const result = await run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', binary, '.'], { cwd: source, env: { ...process.env, ...pinnedGoBuildEnv(arch) } });
     if (result.missing || result.status !== 0)
         throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', `Executor build failed (${arch}). ${PINNED_GO_HINT}\n${result.stderr}`);
     const problem = checkCgiBinary(work, binary, arch);
     if (problem)
         throw new StandaloneBuildError(problem.code, problem.message);
     const lifecycleBinary = join(dir, 'lifecycle');
-    const lifecycleResult = run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', lifecycleBinary, './cmd/lifecycle'], { cwd: source, env: { ...process.env, ...pinnedGoBuildEnv(arch) } });
+    const lifecycleResult = await run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', lifecycleBinary, './cmd/lifecycle'], { cwd: source, env: { ...process.env, ...pinnedGoBuildEnv(arch) } });
     if (lifecycleResult.missing || lifecycleResult.status !== 0)
         throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', `Lifecycle helper build failed (${arch}). ${PINNED_GO_HINT}\n${lifecycleResult.stderr}`);
     const lifecycleProblem = checkCgiBinary(work, lifecycleBinary, arch);

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

@@ -0,0 +1,5 @@
+import type { Findings } from "./findings.js";
+/** INFO lines are `key="value"` (or unquoted `key=value`); quotes may escape `\"` and `\\`. */
+export declare function parseInfo(text: string, findings?: Findings): Map<string, string>;
+/** Checks INFO fields; `payloadPath` is package.tgz on disk, for the checksum. */
+export declare function checkInfoFields(fields: Map<string, string>, payloadPath: string | undefined, findings: Findings): void;

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;