@synopackageland/cli 0.1.0

package/dist/build-spk/generator.js

@@ -0,0 +1,653 @@
+import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import * as tar from "tar";
+import { loadContract, collectInstallParameters } from "../contract/load.js";
+import { renderDsmWindowConfig, resolvedWebLaunch, trustedAppEntryPath, } from "../contract/web-launch.js";
+import { loadCompose } from "../compose/analyze.js";
+import { scanComposePrivilege } from "../compose/privilege.js";
+import { validateProject } from "../validate.js";
+import { writeDsmWindowIcons, writePackageCenterIcons } from "./dsm-icons.js";
+import { infoArchValue } from "./dsm-arch.js";
+import { createReproducibleTar } from "./reproducible-archive.js";
+const FILE_MODE = 0o644;
+const SCRIPT_MODE = 0o755;
+const INSTALL_UIFILE = "install_uifile";
+const UPGRADE_UIFILE = "upgrade_uifile";
+const UNINSTALL_UIFILE = "uninstall_uifile";
+export const EMBEDDED_ATTESTATION_RELATIVE_PATH = ".synopkgland/attestation.jwt";
+const SCRIPT_NAMES = [
+    "preinst",
+    "postinst",
+    "preuninst",
+    "postuninst",
+    "preupgrade",
+    "postupgrade",
+    "start-stop-status",
+];
+export async function buildSpk(options) {
+    if (options.embeddedAttestationToken !== undefined && options.embeddedAttestationToken.length === 0) {
+        return { ok: false, errors: ["EMBEDDED_ATTESTATION_TOKEN_EMPTY"] };
+    }
+    const validation = validateProject(options.project);
+    if (!validation.ok) {
+        return {
+            ok: false,
+            errors: validation.errors.map((e) => e.code),
+        };
+    }
+    const parsed = loadContract(options.project.contractPath);
+    const contract = { ...parsed.contract };
+    if (options.packageIdentity) {
+        contract.package = options.packageIdentity;
+    }
+    if (options.displayname) {
+        contract.displayname = options.displayname;
+    }
+    if (options.spkVersion) {
+        contract.version = options.spkVersion;
+    }
+    const staging = mkdtempSync(join(tmpdir(), "syno-spk-"));
+    try {
+        writeFileSync(join(staging, "INFO"), renderInfo(contract, options.archFamily), "utf8");
+        writePackageCenterIcons(staging);
+        mkdirSync(join(staging, "conf"), { recursive: true });
+        writeFileSync(join(staging, "conf", "privilege"), renderPrivilege(), "utf8");
+        writeFileSync(join(staging, "privilege"), renderPrivilege(), "utf8");
+        mkdirSync(join(staging, "WIZARD_UIFILES"), { recursive: true });
+        const parsedCompose = loadCompose(options.project.composePath);
+        writeFileSync(join(staging, "WIZARD_UIFILES", INSTALL_UIFILE), JSON.stringify(renderInstallWizard(contract, parsedCompose?.compose), null, 2), "utf8");
+        writeFileSync(join(staging, "WIZARD_UIFILES", UPGRADE_UIFILE), JSON.stringify(renderUpgradeWizard(contract, parsedCompose?.compose), null, 2), "utf8");
+        writeFileSync(join(staging, "WIZARD_UIFILES", UNINSTALL_UIFILE), JSON.stringify(renderUninstallWizard(), null, 2), "utf8");
+        mkdirSync(join(staging, "scripts"), { recursive: true });
+        for (const name of SCRIPT_NAMES) {
+            const scriptPath = join(staging, "scripts", name);
+            writeFileSync(scriptPath, renderManagedScript(name, contract), "utf8");
+            chmodSync(scriptPath, SCRIPT_MODE);
+        }
+        mkdirSync(join(staging, "package"), { recursive: true });
+        copyFileSync(options.project.composePath, join(staging, "package", "compose.yaml"));
+        copyFileSync(options.project.contractPath, join(staging, "package", "synology-app.yaml"));
+        const htmlDir = join(options.project.root, "html");
+        if (existsSync(htmlDir)) {
+            cpSync(htmlDir, join(staging, "package", "html"), { recursive: true });
+        }
+        if (options.embeddedAttestationToken !== undefined) {
+            const attestationPath = join(staging, "package", EMBEDDED_ATTESTATION_RELATIVE_PATH);
+            mkdirSync(join(staging, "package", ".synopkgland"), { recursive: true });
+            writeFileSync(attestationPath, options.embeddedAttestationToken, "utf8");
+            chmodSync(attestationPath, FILE_MODE);
+        }
+        if (contract.adminport !== undefined && resolvedWebLaunch(contract) === "dsm-window") {
+            const uiDir = join(staging, "package", "ui");
+            mkdirSync(uiDir, { recursive: true });
+            writeFileSync(join(uiDir, "config"), renderDsmWindowConfig(contract), "utf8");
+            writeDsmWindowIcons(uiDir);
+        }
+        chmodSync(join(staging, "INFO"), FILE_MODE);
+        chmodSync(join(staging, "privilege"), FILE_MODE);
+        chmodSync(join(staging, "WIZARD_UIFILES", INSTALL_UIFILE), FILE_MODE);
+        chmodSync(join(staging, "WIZARD_UIFILES", UPGRADE_UIFILE), FILE_MODE);
+        chmodSync(join(staging, "WIZARD_UIFILES", UNINSTALL_UIFILE), FILE_MODE);
+        chmodSync(join(staging, "package", "compose.yaml"), FILE_MODE);
+        chmodSync(join(staging, "package", "synology-app.yaml"), FILE_MODE);
+        if (contract.adminport !== undefined && resolvedWebLaunch(contract) === "dsm-window") {
+            chmodSync(join(staging, "package", "ui", "config"), FILE_MODE);
+        }
+        const outputPath = options.outputPath ?? join(options.project.root, `${String(contract.package)}.spk`);
+        await createDeterministicSpk(staging, outputPath);
+        return { ok: true, outputPath, errors: [] };
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+function quoteInfo(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function spkVersion(version) {
+    return /-\d+$/.test(version) ? version : `${version}-0001`;
+}
+function renderInfo(contract, archFamily) {
+    const lines = [];
+    const add = (key, value) => {
+        lines.push(`${key}=${quoteInfo(String(value))}`);
+    };
+    add("package", String(contract.package));
+    add("version", spkVersion(String(contract.version)));
+    add("displayname", String(contract.displayname));
+    add("description", String(contract.description));
+    add("maintainer", String(contract.maintainer));
+    add("arch", archFamily === undefined ? "noarch" : infoArchValue(archFamily));
+    add("os_min_ver", String(contract.os_min_ver));
+    // synopkg's Container Manager dep gate reports "not ready" even when CM is
+    // running. Depend on Broker only; Broker's adapter.probe() checks CM at
+    // App install time (CM_CAPABILITY_MISSING).
+    add("install_dep_packages", "SynoPkgLandService>=0.1.0-0016");
+    add("startable", "yes");
+    const launch = resolvedWebLaunch(contract);
+    if (contract.adminprotocol) {
+        add("adminprotocol", String(contract.adminprotocol));
+    }
+    if (launch === "new-page" || launch === "dsm-window") {
+        // Package Center Open uses INFO.adminurl as a same-host path. Do not emit
+        // adminport — that would open the Compose published port (ADR-0053/0062).
+        add("adminurl", trustedAppEntryPath(contract));
+    }
+    else {
+        if (contract.adminport !== undefined) {
+            add("adminport", Number(contract.adminport));
+            // DSM checkport=yes treats INFO.adminport as exclusive. Compose also binds
+            // that host port, so a matching adminport yields synopkg 283 — including
+            // when the same App's container already holds the port. ADR-0053: the
+            // published port is the Web Station upstream, not Package Center Open.
+            add("checkport", "no");
+        }
+        if (contract.adminurl) {
+            add("adminurl", String(contract.adminurl));
+        }
+    }
+    if (launch === "dsm-window") {
+        add("dsmuidir", "ui");
+        add("dsmappname", String(contract.package));
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renderPrivilege() {
+    return `${JSON.stringify({
+        defaults: {
+            "run-as": "package",
+        },
+    }, null, 2)}\n`;
+}
+const SHARED_FOLDER_MOUNT_CONSENT = "此 App 會用你在這台 NAS 選的資料夾；整顆應用都看得到。Shared Folder Mount 是整個 App Instance 的 container access：能打開這個 App 的使用者，容器裡的程式都看得到該 Share，即使該使用者在 File Station 看不到。這不是逐使用者 DSM ACL。要依登入者權限讀寫 NAS 檔案，必須另外核准廣域 files.* 並走 File Gateway。";
+const DSM_USER_RUN_AS_CONSENT = "寫進 Share 的新檔在 File Station 顯示為你選的那位 DSM 使用者。點開此 App 的人共用這個磁碟身分，不是逐登入 ACL。";
+const DSM_USER_UPGRADE_CONSENT = "升級時更換 Container Run-as 不會 chown Share 上的舊檔；只有升級後寫入的新檔才會使用新的磁碟身分。";
+const SHARED_FOLDER_RW_UPGRADE_CONSENT = "此版本把 Share 掛載改為讀寫；容器可讀取並寫入你選的 Share，不再是唯讀。";
+const APP_OWN_SPACE_CONSENT = "此 App 只用 App 自己的空間。";
+const OIDC_COMPAT_CONSENT = "此 App 可用你的 DSM 帳號登入；如果這台 NAS 尚未啟用相容模式，App 會使用自己的登入。登入不等於 File Station ACL。";
+function hasOidcCompat(contract) {
+    const integration = contract.integration;
+    if (!integration || typeof integration !== "object") {
+        return false;
+    }
+    const identity = integration.identity;
+    if (!identity || typeof identity !== "object") {
+        return false;
+    }
+    const oidcCompat = identity.oidc_compat;
+    return Boolean(oidcCompat && typeof oidcCompat === "object");
+}
+function renderFilesCapability(contract) {
+    const permissions = contract.permissions;
+    const files = permissions?.files;
+    if (!files) {
+        return null;
+    }
+    const parts = [];
+    if (files.read) {
+        parts.push("讀取檔案");
+    }
+    if (files.write) {
+        parts.push("寫入檔案");
+    }
+    if (files.delete) {
+        parts.push("刪除檔案");
+    }
+    if (parts.length === 0) {
+        return null;
+    }
+    return `此 App 需要以下檔案能力：${parts.join("、")}。這是每位登入者的 DSM ACL，經 File Gateway。`;
+}
+function volumeSources(compose) {
+    return volumeMounts(compose).map((mount) => mount.source);
+}
+function volumeMounts(compose) {
+    const mounts = [];
+    for (const service of Object.values(compose.services ?? {})) {
+        const volumes = service.volumes;
+        if (!volumes) {
+            continue;
+        }
+        const entries = Array.isArray(volumes) ? volumes : [volumes];
+        for (const entry of entries) {
+            if (typeof entry === "string") {
+                const parts = entry.split(":");
+                const source = parts[0]?.trim() ?? "";
+                if (source) {
+                    const modes = parts
+                        .slice(2)
+                        .flatMap((part) => part.split(","))
+                        .map((part) => part.trim());
+                    mounts.push({ source, readOnly: modes.includes("ro") });
+                }
+            }
+            else if (entry && typeof entry === "object" && "source" in entry) {
+                const record = entry;
+                const source = String(record.source ?? "").trim();
+                if (source) {
+                    mounts.push({ source, readOnly: record.read_only === true });
+                }
+            }
+        }
+    }
+    return mounts;
+}
+function composeUsesOnlyAppSpace(compose) {
+    const sources = volumeSources(compose);
+    if (sources.length === 0) {
+        return false;
+    }
+    return sources.every((source) => source.startsWith("${SYNOPKG_PKGVAR}") || source.startsWith("${SYNO_APP_SECRETS_DIR}"));
+}
+const PRIVILEGE_MAX_WARNING = "此 App 的容器有高權限，接近這台 NAS 的 root、幾乎整台機器。是否安裝由你這位管理員決定。";
+function renderInstallWizard(contract, compose) {
+    const items = [];
+    const params = collectInstallParameters(contract);
+    const hasSharedFolder = params.some((item) => item.param.type === "shared_folder");
+    const hasDsmUser = params.some((item) => item.param.type === "dsm_user");
+    const capabilityText = renderFilesCapability(contract);
+    if (compose && scanComposePrivilege(compose).length > 0) {
+        items.push({
+            desc: PRIVILEGE_MAX_WARNING,
+        });
+    }
+    if (hasOidcCompat(contract)) {
+        items.push({
+            desc: OIDC_COMPAT_CONSENT,
+        });
+    }
+    if (hasSharedFolder) {
+        items.push({
+            desc: SHARED_FOLDER_MOUNT_CONSENT,
+        });
+    }
+    if (hasDsmUser) {
+        items.push({
+            desc: DSM_USER_RUN_AS_CONSENT,
+        });
+    }
+    if (capabilityText) {
+        items.push({
+            desc: capabilityText,
+        });
+    }
+    if (!hasSharedFolder && !capabilityText && compose && composeUsesOnlyAppSpace(compose)) {
+        items.push({
+            desc: APP_OWN_SPACE_CONSENT,
+        });
+    }
+    for (const { name, param } of params) {
+        if (param.type === "secret" && param.generate === true) {
+            continue;
+        }
+        if (param.type === "string") {
+            items.push({
+                type: "textfield",
+                desc: `Install Parameter: ${name}`,
+                subitems: [{
+                        key: name,
+                        desc: name,
+                        defaultValue: param.default ?? "",
+                        validator: { allowBlank: false },
+                    }],
+            });
+            continue;
+        }
+        if (param.type === "boolean") {
+            items.push({
+                type: "multiselect",
+                desc: `Install Parameter: ${name}`,
+                subitems: [{ key: name, desc: name, defaultValue: param.default ?? false }],
+            });
+            continue;
+        }
+        if (param.type === "secret") {
+            items.push({
+                type: "password",
+                desc: `Install Parameter: ${name}`,
+                subitems: [{ key: name, desc: name, validator: { allowBlank: false } }],
+            });
+            continue;
+        }
+        if (param.type === "shared_folder") {
+            items.push({
+                type: "combobox",
+                desc: `Shared Folder: ${name}`,
+                subitems: [{
+                        key: name,
+                        desc: name,
+                        displayField: "name",
+                        valueField: "name",
+                        editable: false,
+                        forceSelection: true,
+                        autoSelect: false,
+                        mode: "remote",
+                        api_store: {
+                            api: "SYNO.Core.Share",
+                            method: "list",
+                            version: 1,
+                            baseParams: { limit: -1, offset: 0 },
+                            root: "shares",
+                            idProperty: "name",
+                            fields: ["name"],
+                        },
+                        validator: { allowBlank: false },
+                    }],
+            });
+            continue;
+        }
+        if (param.type === "dsm_user") {
+            items.push({
+                type: "combobox",
+                desc: `Container Run-as: ${name}`,
+                subitems: [{
+                        key: name,
+                        desc: name,
+                        displayField: "name",
+                        valueField: "name",
+                        editable: false,
+                        forceSelection: true,
+                        autoSelect: false,
+                        mode: "remote",
+                        api_store: {
+                            api: "SYNO.Core.User",
+                            method: "list",
+                            version: 1,
+                            baseParams: { limit: -1, offset: 0 },
+                            root: "users",
+                            idProperty: "name",
+                            fields: ["name"],
+                        },
+                        validator: { allowBlank: false },
+                    }],
+            });
+        }
+    }
+    return [{
+            step_title: "安裝設定",
+            items,
+        }];
+}
+function renderUpgradeWizard(contract, compose) {
+    const installWizard = renderInstallWizard(contract, compose);
+    const params = collectInstallParameters(contract);
+    const sharedFolderNames = params
+        .filter((item) => item.param.type === "shared_folder")
+        .map((item) => item.name);
+    const hasSharedFolder = sharedFolderNames.length > 0;
+    const hasDsmUser = params.some((item) => item.param.type === "dsm_user");
+    const hasReadWriteSharedFolder = hasSharedFolder &&
+        compose !== undefined &&
+        volumeMounts(compose).some((mount) => !mount.readOnly &&
+            sharedFolderNames.some((name) => mount.source === `\${${name}}` || mount.source.startsWith(`\${${name}}/`)));
+    const upgradeConsent = [];
+    if (hasReadWriteSharedFolder) {
+        upgradeConsent.push({
+            desc: SHARED_FOLDER_RW_UPGRADE_CONSENT,
+        });
+    }
+    if (hasDsmUser && hasSharedFolder) {
+        upgradeConsent.push({
+            desc: DSM_USER_UPGRADE_CONSENT,
+        });
+    }
+    if (upgradeConsent.length === 0) {
+        return [{
+                ...installWizard[0],
+                step_title: "升級設定",
+            }];
+    }
+    const firstControl = installWizard[0].items.findIndex((item) => item.subitems !== undefined);
+    const insertAt = firstControl === -1 ? installWizard[0].items.length : firstControl;
+    const items = [...installWizard[0].items];
+    items.splice(insertAt, 0, ...upgradeConsent);
+    return [{
+            ...installWizard[0],
+            step_title: "升級設定",
+            items,
+        }];
+}
+function renderUninstallWizard() {
+    return [{
+            step_title: "解除安裝",
+            items: [
+                {
+                    desc: "勾選 Delete App Data 會永久刪除 App data 與 secrets，但不刪 Shared Folder 或 named volume。平台沒有檢查 Hyper Backup，也未驗證可復原備份。",
+                },
+                {
+                    type: "multiselect",
+                    desc: "Delete App Data",
+                    subitems: [
+                        {
+                            key: "delete_app_data",
+                            desc: "Delete App Data",
+                            defaultValue: false,
+                        },
+                    ],
+                },
+            ],
+        }];
+}
+function renderManagedScript(name, contract) {
+    if (name === "start-stop-status") {
+        return `#!/bin/sh
+INSTALLER="\${BROKER_INSTALLER:-/var/packages/SynoPkgLandService/target/bin/synopkgland-installer}"
+SOCKET="\${BROKER_SOCKET:-/var/packages/SynoPkgLandService/var/installer.sock}"
+case "$1" in
+  start) exit 0 ;;
+  stop) exit 0 ;;
+  status)
+    if [ -x "$INSTALLER" ] && [ -S "$SOCKET" ]; then
+      "$INSTALLER" --socket "$SOCKET" --phase status --attempt-id "status-$$" \\
+        --package-identity "${contract.package}" --package-version "\${SYNOPKG_PKGVER}" \\
+        --package-path "\${SYNOPKG_PKGDEST}" --bundle-path "\${SYNOPKG_PKGDEST}" \\
+        --pkg-var "\${SYNOPKG_PKGVAR}" --pkg-home "\${SYNOPKG_PKGHOME}" >/tmp/synopkgland-status.$$ 2>/dev/null || true
+      if grep -q '"registrationStatus":"removed"' /tmp/synopkgland-status.$$ 2>/dev/null; then
+        rm -f /tmp/synopkgland-status.$$
+        exit 150
+      fi
+      if grep -q '"registrationStatus":"unknown"' /tmp/synopkgland-status.$$ 2>/dev/null; then
+        rm -f /tmp/synopkgland-status.$$
+        exit 4
+      fi
+      rm -f /tmp/synopkgland-status.$$
+    fi
+    exit 0
+    ;;
+  *) exit 1 ;;
+esac
+`;
+    }
+    if (name === "preinst" || name === "preupgrade") {
+        return `#!/bin/sh
+SOCKET="\${BROKER_SOCKET:-/var/packages/SynoPkgLandService/var/installer.sock}"
+if [ ! -S "$SOCKET" ]; then
+  echo "SynoPkgLandService installer socket is not available" >&2
+  exit 1
+fi
+exit 0
+`;
+    }
+    if (name === "postinst" || name === "postupgrade") {
+        return renderInstallerCallScript(contract, name === "postupgrade" ? "update" : "install");
+    }
+    if (name === "preuninst") {
+        return renderInstallerCallScript(contract, "uninstall").replace("set -eu\n", 'set -eu\nif [ "${SYNOPKG_PKG_STATUS:-}" = "UPGRADE" ]; then\n  exit 0\nfi\n');
+    }
+    if (name === "postuninst") {
+        return `#!/bin/sh
+set -eu
+PKGVAR="\${SYNOPKG_PKGVAR}"
+PKGHOME="\${SYNOPKG_PKGHOME}"
+SECRETS="\${PKGHOME}/secrets"
+should_delete=0
+case "\${delete_app_data:-}" in
+  true|True|TRUE|yes|1) should_delete=1 ;;
+esac
+case "\${wizard_delete_app_data:-}" in
+  true|True|TRUE|yes|1) should_delete=1 ;;
+esac
+if [ "$should_delete" -eq 1 ]; then
+  delete_root() {
+    target="$1"
+    if [ ! -e "$target" ] && [ ! -L "$target" ]; then
+      return 0
+    fi
+    if [ -L "$target" ]; then
+      real=$(readlink -f "$target" 2>/dev/null || true)
+      case "$real" in
+        */@appdata/*|*/@apphome/*)
+          ;;
+        *)
+          echo "Delete App Data skipped symlink: $target" >&2
+          return 0
+          ;;
+      esac
+    else
+      real="$target"
+    fi
+    if [ ! -e "$real" ]; then
+      return 0
+    fi
+    chmod -R u+w "$real" 2>/dev/null || true
+    if [ -d "$real" ]; then
+      find "$real" -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
+      leftover=$(find "$real" -mindepth 1 -maxdepth 1 2>/dev/null | head -n 1 || true)
+      if [ -n "$leftover" ]; then
+        echo "Delete App Data remnant: $real" >&2
+      fi
+    else
+      rm -f "$real" || echo "Delete App Data remnant: $real" >&2
+    fi
+  }
+  delete_root "$PKGVAR"
+  delete_root "$SECRETS"
+fi
+exit 0
+`;
+    }
+    return `#!/bin/sh
+exit 0
+`;
+}
+function renderInstallerCallScript(contract, phase) {
+    const params = collectInstallParameters(contract);
+    const secrets = params.filter((item) => item.param.type === "secret");
+    const nonSecrets = params.filter((item) => item.param.type !== "secret");
+    const lines = [
+        "#!/bin/sh",
+        "set -eu",
+        'INSTALLER="${BROKER_INSTALLER:-/var/packages/SynoPkgLandService/target/bin/synopkgland-installer}"',
+        'SOCKET="${BROKER_SOCKET:-/var/packages/SynoPkgLandService/var/installer.sock}"',
+        `PACKAGE_ROOT="/var/packages/${contract.package}"`,
+        'ATTEMPT_ID="${SYNOPKG_PKGNAME}-${SYNOPKG_PKGVER}-$$"',
+        'WORK="$(mktemp -d /tmp/synopkgland-install.XXXXXX)"',
+        'chmod 700 "$WORK"',
+        "cleanup() { rm -rf \"$WORK\"; }",
+        "trap cleanup EXIT",
+        'mkdir -p "${SYNOPKG_PKGVAR}" "${SYNOPKG_PKGHOME}/secrets"',
+        'chmod 770 "${SYNOPKG_PKGVAR}" "${SYNOPKG_PKGHOME}" "${SYNOPKG_PKGHOME}/secrets" 2>/dev/null || true',
+        'chgrp synopkgs "${SYNOPKG_PKGVAR}" "${SYNOPKG_PKGHOME}" "${SYNOPKG_PKGHOME}/secrets" 2>/dev/null || true',
+        'VARS=""',
+        'SECRET_FILES=""',
+    ];
+    for (const { name, param } of secrets) {
+        if (param.generate === true) {
+            continue;
+        }
+        lines.push(`if [ -n "\${${name}+x}" ]; then`);
+        lines.push("  umask 077");
+        lines.push(`  printf '%s' "\$${name}" > "$WORK/${name}"`);
+        lines.push(`  unset ${name}`);
+        lines.push(`  SECRET_FILES="$SECRET_FILES --secret-file ${name}=$WORK/${name}"`);
+        lines.push("fi");
+    }
+    for (const { name } of nonSecrets) {
+        lines.push(`if [ -n "\${${name}+x}" ]; then`);
+        lines.push(`  VARS="$VARS --var ${name}=\$${name}"`);
+        lines.push("fi");
+    }
+    const generateFlags = secrets
+        .filter((item) => item.param.generate === true)
+        .map((item) => `--generate-secret ${item.name}`)
+        .join(" ");
+    lines.push(`"$INSTALLER" --socket "$SOCKET" --phase ${phase} --attempt-id "$ATTEMPT_ID" \\`);
+    lines.push(`  --package-identity "${contract.package}" --package-version "\${SYNOPKG_PKGVER}" \\`);
+    lines.push('  --package-path "$PACKAGE_ROOT/target" --bundle-path "$PACKAGE_ROOT/target" \\');
+    lines.push('  --pkg-var "$PACKAGE_ROOT/var" --pkg-home "$PACKAGE_ROOT/home" \\');
+    if (generateFlags) {
+        lines.push(`  ${generateFlags} \\`);
+    }
+    lines.push('  $VARS $SECRET_FILES');
+    lines.push("exit $?");
+    return `${lines.join("\n")}\n`;
+}
+async function createDeterministicSpk(stagingDir, outputPath) {
+    const payloadDir = join(stagingDir, "package");
+    if (existsSync(payloadDir) && statSync(payloadDir).isDirectory()) {
+        await createReproducibleTar(payloadDir, join(stagingDir, "package.tgz"), { gzip: true });
+        rmSync(payloadDir, { recursive: true, force: true });
+    }
+    await createReproducibleTar(stagingDir, outputPath);
+}
+function walkFiles(root, prefix = "") {
+    const files = [];
+    for (const entry of readdirSync(root).sort()) {
+        const relative = prefix ? `${prefix}/${entry}` : entry;
+        const absolute = join(root, entry);
+        if (statSync(absolute).isDirectory()) {
+            files.push(...walkFiles(absolute, relative));
+        }
+        else {
+            files.push(relative);
+        }
+    }
+    return files;
+}
+export async function digestSpkPayload(spkPath) {
+    const dir = mkdtempSync(join(tmpdir(), "syno-spk-digest-"));
+    try {
+        await extractSpk(spkPath, dir);
+        const hash = createHash("sha256");
+        for (const file of walkFiles(dir)) {
+            hash.update(file);
+            hash.update(readFileSync(join(dir, file)));
+        }
+        return hash.digest("hex");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+export async function extractSpk(spkPath, targetDir) {
+    mkdirSync(targetDir, { recursive: true });
+    await tar.x({ file: spkPath, cwd: targetDir });
+    const tgz = join(targetDir, "package.tgz");
+    if (existsSync(tgz)) {
+        const packageDir = join(targetDir, "package");
+        mkdirSync(packageDir, { recursive: true });
+        await tar.x({ file: tgz, cwd: packageDir });
+    }
+}
+export function readInfoPackage(spkDir) {
+    const info = readFileSync(join(spkDir, "INFO"), "utf8");
+    const match = info.match(/^package="([^"]+)"/m);
+    return match?.[1] ?? null;
+}
+export function collectWizardTexts(spkDir) {
+    const install = readFileSync(join(spkDir, "WIZARD_UIFILES", INSTALL_UIFILE), "utf8");
+    const upgrade = readFileSync(join(spkDir, "WIZARD_UIFILES", UPGRADE_UIFILE), "utf8");
+    const uninstall = readFileSync(join(spkDir, "WIZARD_UIFILES", UNINSTALL_UIFILE), "utf8");
+    return `${install}\n${upgrade}\n${uninstall}`;
+}
+export function readInstallWizard(spkDir) {
+    return JSON.parse(readFileSync(join(spkDir, "WIZARD_UIFILES", INSTALL_UIFILE), "utf8"))[0];
+}
+export function readUpgradeWizard(spkDir) {
+    return JSON.parse(readFileSync(join(spkDir, "WIZARD_UIFILES", UPGRADE_UIFILE), "utf8"))[0];
+}
+export function scriptModeInSpk(spkDir, scriptName) {
+    return statSync(join(spkDir, "scripts", scriptName)).mode & 0o777;
+}

package/dist/build-spk/native-payload.d.ts

@@ -0,0 +1,22 @@
+export type NativeArchiveKind = "tar.gz" | "tar.xz" | "zip" | "raw";
+export interface NativeSource {
+    path?: string;
+    url?: string;
+    sha256?: string;
+    strip_components?: number;
+}
+export interface BuildNativePayloadOptions {
+    source: NativeSource;
+    projectRoot: string;
+    outputTgz: string;
+    /** Build-time network injection. The default uses the platform fetch implementation. */
+    download?: (url: string) => Promise<Buffer>;
+}
+export interface NativePayloadResult {
+    outputTgz: string;
+    sha256: string;
+    sourceSha256: string;
+    entries: string[];
+}
+export declare function archiveKindFor(nameOrUrl: string): NativeArchiveKind;
+export declare function buildNativePayload(options: BuildNativePayloadOptions): Promise<NativePayloadResult>;