@synopackageland/cli 0.9.7 → 0.10.0

package/dist/standalone/inspect-bridge.js

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import * as tar from "tar";
+import { familyOfArchToken, NATIVE_ARCH_FAMILIES } from "../build-spk/dsm-arch.js";
+import { ELF_MACHINE } from "./binary.js";
+import { NODE_SDK_PACKAGE } from "./bridge-app.js";
+import { BRIDGE_JSON, bridgeManifestProblems, PYTHON_VENDOR_DIR } from "./bridge-json.js";
+import { CGI_PAYLOAD_PATH } from "./dsm-window.js";
+/** Files that belong in target/app only: DSM serves everything under ui/ to the browser. */
+const APP_ONLY = [`/${BRIDGE_JSON}`, "/permissions.json", `/${PYTHON_VENDOR_DIR}/synopkgland_app/`, `/node_modules/${NODE_SDK_PACKAGE}/`];
+/**
+ * A Python, Node or Rust App: the runtime CGI binds bridge.json and
+ * permissions.json by digest, the App lives in target/app (never under ui/),
+ * and its entry, SDK and dependencies are in the package.
+ */
+export async function checkBridgeApp(dir, backend, info, payload, findings) {
+    const paths = new Set(payload.map(entry => entry.path));
+    for (const path of payload.map(entry => `/${entry.path}`).filter(path => path.startsWith("/ui/") && APP_ONLY.some(name => path.includes(name)))) {
+        findings.push(`BRIDGE_APP_IN_UI ${path.slice(1)} is an App file and must not be placed in ui/ (DSM serves it directly to the browser)`);
+    }
+    const target = join(dir, "bridge-inspection");
+    mkdirSync(target);
+    // Only read, never run.
+    await tar.x({ file: join(dir, "package.tgz"), cwd: target, filter: path => { const p = path.replace(/^\.\//, ""); return p.startsWith("app/") || p === CGI_PAYLOAD_PATH; } });
+    const app = join(target, "app");
+    const text = existsSync(join(app, BRIDGE_JSON)) ? readFileSync(join(app, BRIDGE_JSON), "utf8") : undefined;
+    const problems = text === undefined ? [`app/${BRIDGE_JSON} is missing`] : bridgeManifestProblems(text);
+    if (problems.length) {
+        findings.push(...problems.map(problem => `BRIDGE_MANIFEST_INVALID ${problem}`));
+        return undefined;
+    }
+    const bridge = JSON.parse(text);
+    if (bridge.runtime !== backend)
+        findings.push(`BRIDGE_MANIFEST_INVALID the runtime "${bridge.runtime}" in app/${BRIDGE_JSON} differs from the backend "${backend}" in sdk-package.json`);
+    checkEntry(app, bridge, info, payload, findings);
+    const permissions = existsSync(join(app, "permissions.json")) ? readFileSync(join(app, "permissions.json")) : undefined;
+    if (!permissions)
+        findings.push("BRIDGE_PERMISSIONS app/permissions.json is missing");
+    else
+        checkPermissions(permissions, bridge, findings);
+    const cgi = existsSync(join(target, CGI_PAYLOAD_PATH)) ? readFileSync(join(target, CGI_PAYLOAD_PATH)) : Buffer.alloc(0);
+    for (const [name, bytes] of [[BRIDGE_JSON, Buffer.from(text)], ["permissions.json", permissions]]) {
+        if (bytes && !cgi.includes(createHash("sha256").update(bytes).digest("hex"))) {
+            findings.push(`BRIDGE_DIGEST_MISMATCH the sha256 bound to ${CGI_PAYLOAD_PATH} is not that of app/${name}; the runtime refuses to run it, rebuild it with synopkgland build`);
+        }
+    }
+    if (backend === "python" && !paths.has(`app/${PYTHON_VENDOR_DIR}/synopkgland_app/__init__.py`))
+        findings.push(`BRIDGE_PYTHON_SDK app/${PYTHON_VENDOR_DIR}/synopkgland_app/ is missing`);
+    if (backend === "node")
+        checkNode(app, bridge, info, findings);
+    return bridge;
+}
+/** root and delegate reach the package's executor; delegate pins the one this SPK ships. */
+export function checkBridgeExecutor(bridge, executor, findings) {
+    const { root, delegate } = bridge.capabilities ?? {};
+    if ((root || delegate) && !executor)
+        findings.push("BRIDGE_EXECUTOR_MISSING app/bridge.json declares root or delegate, but the SPK has no executor");
+    if (delegate && executor && (delegate.executor_digest !== executor.executorDigest || delegate.policy_digest !== executor.policyDigest)) {
+        findings.push("BRIDGE_EXECUTOR_MISMATCH the delegate executor_digest/policy_digest in app/bridge.json differs from the SPK executor");
+    }
+}
+/** The entry exists; a Rust entry is an executable of the SPK's architecture. */
+function checkEntry(app, bridge, info, payload, findings) {
+    const entry = payload.find(file => file.path === `app/${bridge.entry}`);
+    if (!entry) {
+        findings.push(`BRIDGE_ENTRY_MISSING app/${bridge.entry} is missing`);
+        return;
+    }
+    if (bridge.runtime !== "rust")
+        return;
+    if (entry.mode !== "0755")
+        findings.push(`BRIDGE_ENTRY_MISSING app/${bridge.entry} has mode ${entry.mode}; it should be 0755`);
+    const header = readFileSync(join(app, bridge.entry)).subarray(0, 20);
+    const machine = header.length === 20 && header.toString("latin1", 0, 4) === "\x7fELF" ? header.readUInt16LE(18) : undefined;
+    const actual = NATIVE_ARCH_FAMILIES.find(family => ELF_MACHINE[family] === machine);
+    const declared = familyOfArchToken((info.arch ?? "").split(" ")[0] ?? "");
+    if (!actual || (declared && actual !== declared))
+        findings.push(`BRIDGE_ENTRY_ARCH app/${bridge.entry} is not an executable for INFO arch (${declared ?? info.arch})`);
+}
+/** The runtime refuses to start when permissions.json sets a method the manifest does not register. */
+function checkPermissions(bytes, bridge, findings) {
+    let methods;
+    try {
+        methods = Object.keys(JSON.parse(bytes.toString("utf8")).methods ?? {});
+    }
+    catch {
+        findings.push("BRIDGE_PERMISSIONS app/permissions.json is not JSON");
+        return;
+    }
+    const unlisted = methods.filter(method => !bridge.methods?.includes(method));
+    if (unlisted.length)
+        findings.push(`BRIDGE_PERMISSIONS app/permissions.json sets methods bridge.json does not have: ${unlisted.join(", ")}`);
+}
+/** The Node.js package is an install dependency, and every dependency is in node_modules. */
+function checkNode(app, bridge, info, findings) {
+    const node = bridge.node?.package;
+    const deps = (info.install_dep_packages ?? "").split(":").map(dep => dep.replace(/[><=].*$/, ""));
+    if (!node || !deps.includes(node))
+        findings.push(`BRIDGE_NODE_DEPENDENCY INFO install_dep_packages must contain the node.package from bridge.json "${node ?? ""}"`);
+    const missing = [NODE_SDK_PACKAGE];
+    if (existsSync(join(app, "package.json"))) {
+        try {
+            missing.push(...Object.keys(JSON.parse(readFileSync(join(app, "package.json"), "utf8")).dependencies ?? {}));
+        }
+        catch { /* reported as missing below */ }
+    }
+    const absent = [...new Set(missing)].filter(name => !existsSync(join(app, "node_modules", name, "package.json")));
+    if (absent.length)
+        findings.push(`BRIDGE_NODE_MODULES app/node_modules is missing ${absent.join(", ")}`);
+}

package/dist/standalone/inspect-spk.d.ts

@@ -1,7 +1,7 @@
 import { type ExecutorInspection } from "../runtime/executor-inspect.js";
 import type { EntryMode } from "./manifest.js";
 import { type UninstallCleanupItem } from "../runtime/uninstall-cleanup.js";
-export type SpkKind = "native-go" | "native-rust" | "binary" | "container" | "native-layout";
+export type SpkKind = "native-go" | "native-python" | "native-node" | "native-rust" | "binary" | "container" | "native-layout";
 export interface SpkInspection {
     kind?: SpkKind;
     package?: string;

package/dist/standalone/inspect-spk.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { inspectNativeLayout } from "./native-layout.js";
+import { checkBridgeApp, checkBridgeExecutor } from "./inspect-bridge.js";
 import { inspectExecutor, inspectExecutorAnchor } from "../runtime/executor-inspect.js";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -13,7 +14,7 @@ import { daemonConfig, readDaemon } from "./daemon.js";
 import { ROOT_SCRIPT_HINTS } from "./root-ops.js";
 import { DELETE_STATE_KEY } from "../build-spk/uninstall-wizard.js";
 import { readUninstallRecord, stateItemTexts } from "./uninstall.js";
-import { BACKGROUND_UNIT_DIR, BACKGROUND_WORKER_PAYLOAD, backgroundUnitName, renderBackgroundUnit } from "./background.js";
+import { BACKGROUND_UNIT_DIR, BACKGROUND_WORKER_PAYLOAD, BRIDGE_WORKER_ARGS, backgroundUnitName, renderBackgroundUnit } from "./background.js";
 import { renderStandaloneResource } from "./resource.js";
 import { recoverSharedFolder, renderSharedFolderUpgradeWizardFiles, sharedFolderInstallSteps, SHARED_FOLDER_MARKER } from "./shared-folder.js";
 import { renderInstallWizardFiles, renderNativeInstallWizard } from "../build-spk/install-wizard.js";
@@ -26,6 +27,8 @@ import { PORTAL_JSON_RELPATH, PORTAL_MUSTACHE_RELPATH, renderPortalJson, renderP
 import { isPortalAlias } from "../portal/alias.js";
 import { defaultPackageIcons, MAX_ICON_BYTES } from "../build-spk/dsm-icons.js";
 import { decodePng } from "../build-spk/png.js";
+/** The SPK kind of each sdk-package.json backend a CGI is built for: Go itself, or the runtime of an App in another language. */
+const COMPILED_KIND = { go: "native-go", python: "native-python", node: "native-node", rust: "native-rust" };
 /** Reads an SPK without installing it and reports how it would run on DSM. */
 export async function inspectStandaloneSpk(spkPath) {
     return inspectSpk(spkPath, "native-go");
@@ -57,22 +60,22 @@ export async function inspectSpk(spkPath, expectedKind) {
         if (metadataText !== undefined) {
             try {
                 const raw = JSON.parse(metadataText);
-                if (raw.schema !== 2 || !["go", "rust", "binary"].includes(raw.backend) || !Array.isArray(raw.capabilities) || raw.capabilities.some((name) => !["files", "jobs", "identity", "rootOps", "delegate"].includes(String(name))) || new Set(raw.capabilities).size !== raw.capabilities.length || (raw.entry !== undefined && !["admin-only", "app-privilege"].includes(raw.entry)))
+                if (raw.schema !== 2 || !["go", "python", "node", "rust", "binary"].includes(raw.backend) || !Array.isArray(raw.capabilities) || raw.capabilities.some((name) => !["files", "jobs", "identity", "rootOps", "delegate"].includes(String(name))) || new Set(raw.capabilities).size !== raw.capabilities.length || (raw.entry !== undefined && !["admin-only", "app-privilege"].includes(raw.entry)))
                     throw new Error();
                 metadata = raw;
             }
             catch {
-                findings.push("sdk-package.json 不符合 schema 2 capability inventory。");
+                findings.push("sdk-package.json does not match the schema 2 capability inventory.");
             }
         }
         const uninstallHook = metadata.uninstall === undefined ? undefined : readUninstallRecord(metadata.uninstall, metadata.capabilities?.includes("rootOps") === true);
         if (metadata.uninstall !== undefined && !uninstallHook)
-            findings.push("UNINSTALL_RECORD_INVALID sdk-package.json 的 uninstall 不是 synopkgland build 寫出的 uninstall 設定。");
+            findings.push("UNINSTALL_RECORD_INVALID the uninstall in sdk-package.json is not the uninstall setting synopkgland build writes.");
         const binaryBackend = metadata.backend === "binary";
         // A strict standalone inspection names the language the CGI was built from.
-        const compiled = metadata.backend === "rust" ? "native-rust" : "native-go";
+        const compiled = COMPILED_KIND[metadata.backend ?? "go"] ?? "native-go";
         const kind = (expectedKind === "native-go" ? compiled : expectedKind) ?? (paths.has("compose.yaml") ? "container" : binaryBackend ? "binary" : compiled);
-        const compiledKind = kind === "native-go" || kind === "native-rust";
+        const compiledKind = Object.values(COMPILED_KIND).includes(kind);
         const standalone = compiledKind || kind === "binary";
         const info = readInfo(join(dir, "INFO"), findings, kind);
         await checkArch(dir, info, kind, paths.has(CGI_PAYLOAD_PATH), findings);
@@ -81,19 +84,20 @@ export async function inspectSpk(spkPath, expectedKind) {
         // A Compose App has no executor, so its SPK never carries a portal.
         const portal = standalone ? await recoverPortal(dir, info, `SYNO.SDS.${info.package}.Instance`, paths, payload, findings) : undefined;
         if (portal && info.os_min_ver && OS_MIN_VER.test(info.os_min_ver) && !isDsmAtLeast(info.os_min_ver, PORTAL_MIN_DSM)) {
-            findings.push(`INFO os_min_ver「${info.os_min_ver}」低於 portal 需要的 DSM ${PORTAL_MIN_DSM}；${PORTAL_MIN_DSM_REASON}`);
+            findings.push(`INFO os_min_ver "${info.os_min_ver}" is below the DSM ${PORTAL_MIN_DSM} a portal needs; ${PORTAL_MIN_DSM_REASON}`);
         }
         checkConf(dir, findings, kind, background, sharedFolder, info.package, portal);
         checkScripts(dir, findings);
         checkUninstall(dir, findings);
         if (kind === "container")
             await checkContainerExposure(dir, join(dir, "package.tgz"), findings);
+        const bridge = compiledKind && kind !== "native-go" ? await checkBridgeApp(dir, metadata.backend, info, payload, findings) : undefined;
         const hasExecutor = (metadata.capabilities ?? []).some(name => name === "rootOps" || name === "delegate") || paths.has("executor/executor");
         if (standalone && portal && !hasExecutor)
-            findings.push("PORTAL_REQUIRES_EXECUTOR portal 需要 executor 層級（rootOps 或 delegate）：解除安裝後只有 root purge 能讓 nginx 停止提供別名");
+            findings.push("PORTAL_REQUIRES_EXECUTOR portal needs the executor level (rootOps or delegate): after uninstall only a root purge can stop nginx serving the alias");
         const daemon = standalone ? await checkDaemon(dir, info, paths, payload, findings, hasExecutor, background) : undefined;
         if (background)
-            checkBackground(dir, info, payload, findings, hasExecutor, daemon);
+            checkBackground(dir, info, payload, findings, hasExecutor, daemon, kind !== "native-go");
         let executor;
         if ((metadata.capabilities ?? []).some(name => name === "rootOps" || name === "delegate") || paths.has("executor/executor")) {
             const executorDir = join(dir, "executor-inspection");
@@ -105,10 +109,10 @@ export async function inspectSpk(spkPath, expectedKind) {
             if (executor)
                 findings.push(...inspectExecutorAnchor(readFileSync(join(dir, "INFO"), "utf8"), executor.executorDigest));
             if (executor?.policy.portal && info.os_min_ver && OS_MIN_VER.test(info.os_min_ver) && !isDsmAtLeast(info.os_min_ver, PORTAL_EXECUTOR_MIN_DSM)) {
-                findings.push(`INFO os_min_ver「${info.os_min_ver}」低於 executor 註冊 portal 需要的 DSM ${PORTAL_EXECUTOR_MIN_DSM}`);
+                findings.push(`INFO os_min_ver "${info.os_min_ver}" is below the DSM ${PORTAL_EXECUTOR_MIN_DSM} the executor needs to register a portal`);
             }
             if (executor && executor.policy.purge !== uninstallHook?.uninstall.purge.root)
-                findings.push(`UNINSTALL_ROOT_POLICY_MISMATCH executor policy 的 purge「${executor.policy.purge ?? ""}」與 uninstall.purge.root「${uninstallHook?.uninstall.purge.root ?? ""}」不同。`);
+                findings.push(`UNINSTALL_ROOT_POLICY_MISMATCH the executor policy purge "${executor.policy.purge ?? ""}" differs from uninstall.purge.root "${uninstallHook?.uninstall.purge.root ?? ""}".`);
             if (payload.find(p => p.path === "executor/executor")?.mode !== "0755")
                 findings.push("Executor must be executable.");
             if (payload.find(p => p.path === "executor/lifecycle")?.mode !== "0755")
@@ -125,6 +129,8 @@ export async function inspectSpk(spkPath, expectedKind) {
                     findings.push(`Executor WIZARD_UIFILES/${name} is missing cleanup guidance.`);
             }
         }
+        if (bridge)
+            checkBridgeExecutor(bridge, executor, findings);
         if (background && daemon && (executor?.policy.lifetime !== 'until-revoked' || !metadata.capabilities?.includes('delegate'))) {
             findings.push('daemon/background combination requires an explicitly pinned until-revoked delegate policy.');
         }
@@ -135,10 +141,10 @@ export async function inspectSpk(spkPath, expectedKind) {
         const icon = inspectPackageIcons(dir, findings);
         const cgiEntry = payload.find((entry) => entry.path === CGI_PAYLOAD_PATH);
         if (standalone && !cgiEntry) {
-            findings.push(`payload 沒有 ${CGI_PAYLOAD_PATH}`);
+            findings.push(`the payload has no ${CGI_PAYLOAD_PATH}`);
         }
         else if (cgiEntry && cgiEntry.mode !== "0755") {
-            findings.push(`${CGI_PAYLOAD_PATH} 的 mode 是 ${cgiEntry.mode}，應為 0755`);
+            findings.push(`${CGI_PAYLOAD_PATH} has mode ${cgiEntry.mode}; it should be 0755`);
         }
         return {
             kind,
@@ -176,7 +182,7 @@ async function checkEntryLauncher(dir, pkg, entry, findings) {
     const expected = entryLauncherAccess(entry);
     const fields = ["allUsers", "grantPrivilege", "advanceGrantPrivilege"];
     if (!launcher || fields.some(field => launcher[field] !== expected[field])) {
-        findings.push(`ENTRY_LAUNCHER_MISMATCH sdk-package.json 宣告 entry: ${entry}，但 ui/config 的 launcher 不是 ${JSON.stringify(expected)}；請用 synopkgland build 重新產生`);
+        findings.push(`ENTRY_LAUNCHER_MISMATCH sdk-package.json declares entry: ${entry}, but the ui/config launcher is not ${JSON.stringify(expected)}; regenerate it with synopkgland build`);
     }
 }
 /** Package Center shows PACKAGE_ICON at 64 and 256 px; the package source refuses a release whose icon is over 256 KiB. */
@@ -186,16 +192,16 @@ function inspectPackageIcons(dir, findings) {
         if (!bytes)
             continue;
         if (bytes.length > MAX_ICON_BYTES) {
-            findings.push(`${name} 有 ${bytes.length} bytes，超過 package source 的 256 KiB 上限；上架後整個版本會被拒收`);
+            findings.push(`${name} is ${bytes.length} bytes, over the package source limit of 256 KiB; publishing rejects the whole version`);
             continue;
         }
         try {
             const image = decodePng(bytes);
             if (image.width !== size || image.height !== size)
-                findings.push(`${name} 是 ${image.width}×${image.height}，Package Center 需要 ${size}×${size}`);
+                findings.push(`${name} is ${image.width}x${image.height}; Package Center needs ${size}x${size}`);
         }
         catch (error) {
-            findings.push(`${name}：${error.message}`);
+            findings.push(`${name}: ${error.message}`);
         }
     }
     const big = readOptionalBytes(join(dir, "PACKAGE_ICON_256.PNG"));
@@ -212,20 +218,20 @@ const OS_MIN_VER = /^7\.\d+(\.\d+)?-\d+$/;
 /** INFO os_min_ver and arch must be values DSM accepts, and arch must match the shipped CGI. */
 async function checkArch(dir, info, kind, hasCgi, findings) {
     if (info.os_min_ver && !OS_MIN_VER.test(info.os_min_ver)) {
-        findings.push(`INFO os_min_ver「${info.os_min_ver}」不是 DSM 7 的 <版本>-<build>（例如 7.1-42661）`);
+        findings.push(`INFO os_min_ver "${info.os_min_ver}" is not the DSM 7 <version>-<build> (for example 7.1-42661)`);
     }
     else if (kind === "container" && info.os_min_ver && !isDsmAtLeast(info.os_min_ver, CONTAINER_MIN_DSM)) {
-        findings.push(`INFO os_min_ver「${info.os_min_ver}」低於容器 App 需要的 DSM ${CONTAINER_MIN_DSM}；docker-project／Container Manager 從 DSM 7.2.1 才有，在更早的 DSM 會安裝但無法啟動`);
+        findings.push(`INFO os_min_ver "${info.os_min_ver}" is below the DSM ${CONTAINER_MIN_DSM} a container App needs; docker-project/Container Manager starts at DSM 7.2.1, so on an earlier DSM it installs but cannot start`);
     }
     const tokens = (info.arch ?? "").split(" ").filter(Boolean);
     if (tokens.length === 0 || tokens.includes("noarch"))
         return;
     for (const token of tokens.filter(token => !familyOfArchToken(token))) {
-        findings.push(`INFO arch 含未知的 platform「${token}」`);
+        findings.push(`INFO arch contains an unknown platform "${token}"`);
     }
     const families = new Set(tokens.map(familyOfArchToken).filter(family => family !== undefined));
     if (families.size > 1) {
-        findings.push(`INFO arch 混用多個架構（${[...families].join("、")}）；一個 SPK 只含一種架構的 binary`);
+        findings.push(`INFO arch mixes several architectures (${[...families].join(", ")}); an SPK contains binaries for one architecture only`);
     }
     if (kind === "container" || !hasCgi || families.size !== 1)
         return;
@@ -238,16 +244,16 @@ async function checkArch(dir, info, kind, hasCgi, findings) {
     const machine = header.length === 20 && header.toString("latin1", 0, 4) === "\x7fELF" ? header.readUInt16LE(18) : undefined;
     const actual = NATIVE_ARCH_FAMILIES.find(family => ELF_MACHINE[family] === machine);
     if (actual && actual !== declared) {
-        findings.push(`INFO arch 宣告 ${declared}，但 ${CGI_PAYLOAD_PATH} 是 ${actual} 的執行檔`);
+        findings.push(`INFO arch declares ${declared}, but ${CGI_PAYLOAD_PATH} is a ${actual} executable`);
     }
 }
 async function checkDaemon(dir, info, paths, payload, findings, executor, background) {
     if (![...paths].some(path => path.startsWith("daemon/")))
         return;
     if (info.precheckstartstop !== "yes")
-        findings.push('daemon INFO 必須明確設定 precheckstartstop="yes"');
+        findings.push("daemon INFO must explicitly set precheckstartstop=\"yes\"");
     if (payload.find(p => p.path === "daemon/control")?.mode !== "0755")
-        findings.push("daemon/control 缺少或非 executable");
+        findings.push("daemon/control is missing or not executable");
     const unpacked = join(dir, "daemon-inspection");
     // Extract only the bounded config; the payload executable is never run.
     const { mkdirSync } = await import("node:fs");
@@ -271,17 +277,17 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
             throw new Error("non-canonical daemon config");
         for (const hook of ["start-stop-status", "preupgrade", "preuninst"]) {
             if (readFileSync(join(dir, "scripts", hook), "utf8") !== renderStandaloneScript(hook, manifest))
-                findings.push(`daemon scripts/${hook} 與固定 lifecycle 不符`);
+                findings.push(`daemon scripts/${hook} does not match the fixed lifecycle`);
         }
         return daemon;
     }
     catch {
-        findings.push("daemon/config.json 或 payload 不符合固定 daemon 契約");
+        findings.push("daemon/config.json or the payload does not match the fixed daemon contract");
     }
 }
 function readInfo(path, findings, kind) {
     if (!existsSync(path)) {
-        findings.push("缺少 INFO");
+        findings.push("INFO is missing");
         return {};
     }
     const info = {};
@@ -293,14 +299,16 @@ function readInfo(path, findings, kind) {
     }
     for (const key of ["package", "version", "arch", "os_min_ver"]) {
         if (!info[key]) {
-            findings.push(`INFO 缺少 ${key}`);
+            findings.push(`INFO is missing ${key}`);
         }
     }
     if (kind !== "container" && (info.thirdparty !== "yes" || info.dsmuidir !== "ui")) {
-        findings.push('INFO 必須有 thirdparty="yes" 與 dsmuidir="ui"，DSM 才會提供 /webman/3rdparty/<package>/');
+        findings.push("INFO must have thirdparty=\"yes\" and dsmuidir=\"ui\" for DSM to serve /webman/3rdparty/<package>/");
     }
-    if (info.install_dep_packages && !(kind === "container" && info.install_dep_packages.split(":").every(dep => /^(WebStation|ContainerManager)([><=].*)?$/.test(dep)))) {
-        findings.push(`INFO 依賴其他套件：${info.install_dep_packages}`);
+    // A container needs Container Manager (and Web Station for a portal); a Node App the Node.js it runs on.
+    const allowed = kind === "container" ? /^(WebStation|ContainerManager)([><=].*)?$/ : kind === "native-node" ? /^Node\.js_v[0-9]{2}([><=].*)?$/ : undefined;
+    if (info.install_dep_packages && !(allowed && info.install_dep_packages.split(":").every(dep => allowed.test(dep)))) {
+        findings.push(`INFO depends on other packages: ${info.install_dep_packages}`);
     }
     return info;
 }
@@ -311,11 +319,11 @@ async function checkContainerExposure(dir, packageTgz, findings) {
     await tar.x({ file: packageTgz, cwd: extracted, filter: path => path.replace(/^\.\//, "") === "compose.yaml" });
     const compose = loadCompose(join(extracted, "compose.yaml"))?.compose;
     for (const exposure of compose ? listPortExposures(compose).filter(e => !e.loopbackOnly) : []) {
-        findings.push(`CONTAINER_PORT_EXPOSED ${exposure.service}: ${exposure.entry} 綁在所有網路介面，可不經 DSM 驗證直接連線；請改綁 127.0.0.1`);
+        findings.push(`CONTAINER_PORT_EXPOSED ${exposure.service}: ${exposure.entry} binds to every network interface, so it is reachable without DSM verification; bind it to 127.0.0.1`);
     }
     try {
         if (JSON.parse(readFileSync(join(dir, "conf", "resource"), "utf8")).webservice) {
-            findings.push("CONTAINER_ANONYMOUS_PORTAL conf/resource 註冊了 Web Station portal，任何人不需登入 DSM 即可開啟（integration.web.access: public）");
+            findings.push("CONTAINER_ANONYMOUS_PORTAL conf/resource registers a Web Station portal that anyone can open without signing in to DSM (integration.web.access: public)");
         }
     }
     catch { /* checkConf already reports an unreadable conf/resource */ }
@@ -328,29 +336,29 @@ function checkConf(dir, findings, kind, background, sharedFolder, pkg, portal) {
     const entries = existsSync(confDir) ? readdirSync(confDir) : [];
     const nativeResource = kind !== "container" ? renderStandaloneResource({ package: pkg ?? "", capabilities: background ? { jobs: { worker: "sha256-v1" } } : {}, ...(sharedFolder ? { sharedFolder } : {}) }, portal) : undefined;
     if (nativeResource !== undefined && readOptional(join(confDir, "resource")) !== nativeResource) {
-        findings.push(`conf/resource 必須是 ${nativeResource}（只有官方 data-share、systemd-user-unit 與 web-config，且與 install.sharedFolder、portal 宣告一致）`);
+        findings.push(`conf/resource must be ${nativeResource} (only the official data-share, systemd-user-unit and web-config, and consistent with the install.sharedFolder and portal declarations)`);
     }
     for (const name of entries) {
         if (name !== "privilege" && !(kind === "container" && name === "resource") && !(nativeResource !== undefined && name === "resource") && !(background && name === "systemd")) {
-            findings.push(`conf/${name} 會向 DSM 註冊額外資源；Standalone Package 不產生它`);
+            findings.push(`conf/${name} registers an extra resource with DSM; a Standalone Package does not produce it`);
         }
     }
     if (kind === "container") {
         try {
             const resource = JSON.parse(readFileSync(join(confDir, "resource"), "utf8"));
             if (!resource["docker-project"])
-                findings.push("container 缺少 docker-project resource");
+                findings.push("the container is missing the docker-project resource");
             for (const key of Object.keys(resource)) {
                 if (!["docker-project", "webservice"].includes(key))
-                    findings.push(`未知 container resource: ${key}`);
+                    findings.push(`Unknown container resource: ${key}`);
             }
         }
         catch {
-            findings.push("container 缺少有效的 conf/resource");
+            findings.push("the container is missing a valid conf/resource");
         }
     }
     if (!entries.includes("privilege")) {
-        findings.push("缺少 conf/privilege（DSM 7 必須以 package 帳號執行）");
+        findings.push("conf/privilege is missing (DSM 7 must run as the package account)");
         return;
     }
     let privilege;
@@ -358,36 +366,36 @@ function checkConf(dir, findings, kind, background, sharedFolder, pkg, portal) {
         privilege = JSON.parse(readFileSync(join(confDir, "privilege"), "utf8"));
     }
     catch {
-        findings.push("conf/privilege 不是 JSON");
+        findings.push("conf/privilege is not JSON");
         return;
     }
     const defaults = privilege.defaults;
     if (defaults?.["run-as"] !== "package") {
-        findings.push('conf/privilege 的 defaults.run-as 必須是 "package"');
+        findings.push("conf/privilege defaults.run-as must be \"package\"");
     }
     for (const key of ["tool", "ctrl-script", "executable", "join-groupname"]) {
         if (key in privilege) {
-            findings.push(`conf/privilege 要求 ${key}（root 或額外群組權限）`);
+            findings.push(`conf/privilege requires ${key} (root or extra group privileges)`);
         }
     }
 }
 /** The opt-in package user unit must be exactly what the generator writes. */
-function checkBackground(dir, info, payload, findings, executor, daemon) {
+function checkBackground(dir, info, payload, findings, executor, daemon, bridge = false) {
     const pkg = info.package;
     if (!pkg)
         return;
     const read = (path) => existsSync(join(dir, path)) ? readFileSync(join(dir, path), "utf8") : undefined;
     if (payload.find(p => p.path === BACKGROUND_WORKER_PAYLOAD)?.mode !== "0755")
-        findings.push(`${BACKGROUND_WORKER_PAYLOAD} 缺少或非 executable`);
+        findings.push(`${BACKGROUND_WORKER_PAYLOAD} is missing or not executable`);
     if (info.precheckstartstop !== "yes")
-        findings.push('background INFO 必須明確設定 precheckstartstop="yes"（prestart 復原失去 socket 的套件使用者 manager）');
+        findings.push("background INFO must explicitly set precheckstartstop=\"yes\" (prestart recovers the package user manager that lost its socket)");
     const units = existsSync(join(dir, BACKGROUND_UNIT_DIR)) ? readdirSync(join(dir, BACKGROUND_UNIT_DIR)) : [];
     const unit = backgroundUnitName(pkg);
-    if (units.length !== 1 || units[0] !== unit || read(`${BACKGROUND_UNIT_DIR}/${unit}`) !== renderBackgroundUnit(pkg)) {
-        findings.push(`${BACKGROUND_UNIT_DIR} 必須只有固定的 ${unit}（套件帳號執行，無 User=、無 root）`);
+    if (units.length !== 1 || units[0] !== unit || read(`${BACKGROUND_UNIT_DIR}/${unit}`) !== renderBackgroundUnit(pkg, bridge ? BRIDGE_WORKER_ARGS : [])) {
+        findings.push(`${BACKGROUND_UNIT_DIR} must contain only the fixed ${unit} (runs as the package account, no User=, no root)`);
     }
     if (read("scripts/start-stop-status") !== renderStandaloneScript("start-stop-status", { package: pkg, ...(daemon ? { daemon } : {}), capabilities: { jobs: { worker: "sha256-v1" }, ...(executor ? { rootOps: true } : {}) } }))
-        findings.push("background scripts/start-stop-status 與固定 synosystemctl lifecycle 不符");
+        findings.push("background scripts/start-stop-status does not match the fixed synosystemctl lifecycle");
 }
 /**
  * `install.sharedFolder` is recovered from the postinst marker. The install
@@ -400,18 +408,18 @@ function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal,
     const present = (existsSync(wizardDir) ? readdirSync(wizardDir) : []).filter(name => /^(install|upgrade)_uifile(_|\.|$)/.test(name)).sort();
     const postinst = readOptional(join(dir, "scripts/postinst"));
     if (!folder && postinst?.includes(SHARED_FOLDER_MARKER))
-        findings.push("scripts/postinst 的 install.sharedFolder 宣告無效");
+        findings.push("the install.sharedFolder declaration in scripts/postinst is invalid");
     if (!pkg)
         return;
     const wizards = expectedWizardFiles(pkg, folder, selected, portal);
-    const source = selected ? "install-selected policy" : folder ? "install.sharedFolder 宣告" : portal ? "portal 宣告" : "native-go 預設安裝精靈";
+    const source = selected ? "the install-selected policy" : folder ? "the install.sharedFolder declaration" : portal ? "the portal declaration" : "the native-go default install wizard";
     // The default native wizard is optional; a declared shared folder or portal needs all of its files.
     for (const name of folder || selected || portal ? Object.keys(wizards) : present.filter(n => n in wizards)) {
         if (readOptional(join(wizardDir, name)) !== wizards[name])
-            findings.push(`WIZARD_UIFILES/${name} 與${source}不符`);
+            findings.push(`WIZARD_UIFILES/${name} does not match ${source}`);
     }
     for (const name of present.filter(n => !(n in wizards)))
-        findings.push(`WIZARD_UIFILES/${name} 不是${source}產生的精靈檔`);
+        findings.push(`WIZARD_UIFILES/${name} is not a wizard file produced by ${source}`);
     if (selected) {
         for (const hook of ['preinst', 'postinst']) {
             if (!readOptional(join(dir, 'scripts', hook))?.includes(renderDelegateInstallDraft(pkg, hook === 'preinst')))
@@ -422,7 +430,7 @@ function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal,
         return;
     for (const hook of ["postinst", "postupgrade"]) {
         if (readOptional(join(dir, "scripts", hook)) !== renderStandaloneScript(hook, { package: pkg, sharedFolder: folder, ...(selected ? { capabilities: { delegate: { scope: "install-selected" } } } : executor ? { capabilities: { rootOps: true } } : {}), ...portalManifest(portal) })) {
-            findings.push(`scripts/${hook} 與 install.sharedFolder 宣告的固定腳本不符`);
+            findings.push(`scripts/${hook} does not match the fixed script declared by install.sharedFolder`);
         }
     }
 }
@@ -463,18 +471,18 @@ async function recoverPortal(dir, info, appId, paths, payload, findings) {
         return portal;
     }
     catch {
-        findings.push("PORTAL_INVALID etc/portal.json、etc/portal.mustache 或 lifecycle 不符合固定 Application Portal 契約（應開啟套件自己的 DSM 視窗）");
+        findings.push("PORTAL_INVALID etc/portal.json, etc/portal.mustache or the lifecycle does not match the fixed Application Portal contract (it should open the package's own DSM window)");
     }
 }
 function checkScripts(dir, findings) {
     const scriptsDir = join(dir, "scripts");
     if (!existsSync(join(scriptsDir, "start-stop-status"))) {
-        findings.push("缺少 scripts/start-stop-status");
+        findings.push("scripts/start-stop-status is missing");
     }
     for (const name of existsSync(scriptsDir) ? readdirSync(scriptsDir) : []) {
         const body = readFileSync(join(scriptsDir, name), "utf8");
         if (ROOT_SCRIPT_HINTS.some((pattern) => pattern.test(body))) {
-            findings.push(`scripts/${name} 嘗試取得 root 權限（sudo、chown root 或 setuid）`);
+            findings.push(`scripts/${name} tries to gain root (sudo, chown root or setuid)`);
         }
     }
 }
@@ -515,21 +523,21 @@ function checkUninstall(dir, findings) {
     const deletes = DELETE_COMMAND.test(body);
     if (deletes) {
         if (!UPGRADE_GUARD.test(body))
-            findings.push('UNINSTALL_NO_UPGRADE_GUARD scripts/postuninst 刪除資料但沒有 [ "$SYNOPKG_PKG_STATUS" != UPGRADE ] 防護，升級時會誤刪');
+            findings.push("UNINSTALL_NO_UPGRADE_GUARD scripts/postuninst deletes data without the [ \"$SYNOPKG_PKG_STATUS\" != UPGRADE ] guard, so an upgrade deletes it by mistake");
         if (!/is_package_area\(\)\s*\{/.test(body) || !/if ! is_package_area "\$real"/.test(body))
-            findings.push("UNINSTALL_UNSAFE_DELETE scripts/postuninst 刪除的路徑沒有驗證落在 /volumeN/@appdata|@apphome|@appconf|@appstore/<package>；變數為空或指向別處時會刪錯資料");
+            findings.push("UNINSTALL_UNSAFE_DELETE scripts/postuninst does not verify the deleted paths are under /volumeN/@appdata|@apphome|@appconf|@appstore/<package>; an empty or redirected variable deletes the wrong data");
         for (const line of body.split("\n").filter(l => DELETE_COMMAND.test(l))) {
             for (const path of line.match(/\/volume\w*\/(?!@app(data|home|conf|store)\/)[^\s"'$;]*/g) ?? [])
-                findings.push(`UNINSTALL_UNSAFE_DELETE scripts/postuninst 刪除 ${path}，不在套件自己的 @app* 目錄內`);
+                findings.push(`UNINSTALL_UNSAFE_DELETE scripts/postuninst deletes ${path}, which is not inside the package's own @app* directory`);
         }
         if (!boxes.some(box => box.name === "uninstall_uifile"))
-            findings.push("UNINSTALL_WIZARD_MISSING postuninst 會刪除資料，但 WIZARD_UIFILES/uninstall_uifile 沒有 pkgwizard_remove_additional 勾選框，使用者無法選擇");
+            findings.push("UNINSTALL_WIZARD_MISSING postuninst deletes data, but WIZARD_UIFILES/uninstall_uifile has no pkgwizard_remove_additional checkbox, so the user cannot choose");
     }
     for (const box of boxes) {
         if (box.defaultValue !== false)
-            findings.push(`UNINSTALL_WIZARD_DEFAULT_CHECKED WIZARD_UIFILES/${box.name} 的 ${box.key} 預設必須不勾（保留資料）`);
+            findings.push(`UNINSTALL_WIZARD_DEFAULT_CHECKED ${box.key} in WIZARD_UIFILES/${box.name} must be unchecked by default (keep the data)`);
         if (!body.includes(box.key))
-            findings.push(`UNINSTALL_WIZARD_NOT_HONOURED WIZARD_UIFILES/${box.name} 提供 ${box.key} 勾選框，但 scripts/postuninst 沒有讀它`);
+            findings.push(`UNINSTALL_WIZARD_NOT_HONOURED WIZARD_UIFILES/${box.name} provides the ${box.key} checkbox, but scripts/postuninst does not read it`);
     }
 }
 /** The App's delete-state box keeps the state by default, and preuninst hands its answer to the App hook. */
@@ -538,14 +546,14 @@ function checkStateBoxes(dir, boxes, findings) {
     const body = existsSync(script) ? readFileSync(script, "utf8") : "";
     for (const box of boxes) {
         if (box.defaultValue !== false)
-            findings.push(`UNINSTALL_STATE_DEFAULT_CHECKED WIZARD_UIFILES/${box.name} 的 ${box.key} 預設必須不勾（保留 App 狀態）`);
+            findings.push(`UNINSTALL_STATE_DEFAULT_CHECKED ${box.key} in WIZARD_UIFILES/${box.name} must be unchecked by default (keep the App state)`);
         if (!body.includes(box.key))
-            findings.push(`UNINSTALL_STATE_NOT_HONOURED WIZARD_UIFILES/${box.name} 提供 ${box.key} 勾選框，但 scripts/preuninst 沒有讀它`);
+            findings.push(`UNINSTALL_STATE_NOT_HONOURED WIZARD_UIFILES/${box.name} provides the ${box.key} checkbox, but scripts/preuninst does not read it`);
     }
 }
 export async function listPayload(packageTgz, findings) {
     if (!existsSync(packageTgz)) {
-        findings.push("缺少 package.tgz");
+        findings.push("package.tgz is missing");
         return [];
     }
     const payload = [];
@@ -555,16 +563,16 @@ export async function listPayload(packageTgz, findings) {
             const path = entry.path.replace(/^\.\//, "");
             const mode = (entry.mode ?? 0) & 0o7777;
             if (entry.type === "SymbolicLink" || entry.type === "Link") {
-                findings.push(`payload 含連結：${path}`);
+                findings.push(`payload contains a link: ${path}`);
             }
             if (path.startsWith("/") || path.split("/").includes("..")) {
-                findings.push(`payload 路徑跳出套件目錄：${path}`);
+                findings.push(`payload path escapes the package directory: ${path}`);
             }
             if (mode & 0o6000) {
-                findings.push(`payload 含 setuid/setgid 檔案：${path}`);
+                findings.push(`payload contains a setuid/setgid file: ${path}`);
             }
             if (mode & 0o002) {
-                findings.push(`payload 含所有人可寫的檔案：${path}`);
+                findings.push(`payload contains a world-writable file: ${path}`);
             }
             if (entry.type === "File") {
                 payload.push({ path, mode: mode.toString(8).padStart(4, "0") });

package/dist/standalone/lifecycle.js

@@ -47,7 +47,7 @@ function renderStandaloneScriptBody(name, manifest) {
         }
         if (name === "preuninst")
             return renderExecutorPreuninst(manifest, workerStop, stopWorker, workerResult, request);
-        return `#!/bin/sh\n${workerStop}${stopWorker}${request("stop")}${manifest.daemon ? renderDaemonScript(name, manifest).replace("#!/bin/sh\n", "") : workerResult}`;
+        return `#!/bin/sh\n${renderExecutorUpgradeStop(manifest.package)}${workerStop}${stopWorker}${UPGRADE_STOP} || exit $?\n${manifest.daemon ? renderDaemonScript(name, manifest).replace("#!/bin/sh\n", "") : workerResult}`;
     }
     if (name === "postuninst")
         return renderPackagePostuninst(manifest.package);
@@ -85,11 +85,11 @@ function renderDelegatedDaemonScript(name, manifest) {
     const worker = (action) => `/usr/syno/bin/synosystemctl ${action} ${backgroundUnitName(pkg)}`;
     // Try every owner even on failure; never leave protected ingress open merely
     // because a producer could not stop. A partial teardown remains a failure.
-    const stop = (daemonAction, executorAction) => `result=0\nstop_background_worker || result=1\n${daemon} ${daemonAction} ${paths} || result=1\n${executor(executorAction)} || result=1\nexit "$result"\n`;
+    const stop = (daemonAction, executorAction, executorStop = executor(executorAction)) => `result=0\nstop_background_worker || result=1\n${daemon} ${daemonAction} ${paths} || result=1\n${executorStop} || result=1\nexit "$result"\n`;
     const workerStop = renderBackgroundWorkerStop(pkg);
     if (name !== 'start-stop-status') {
         if (name === 'preupgrade')
-            return `#!/bin/sh\n${workerStop}${stop('stop', 'stop')}`;
+            return `#!/bin/sh\n${renderExecutorUpgradeStop(pkg)}${workerStop}${stop('stop', 'stop', UPGRADE_STOP)}`;
         const purge = manifest.uninstall
             ? stop(manifest.daemon?.uninstall_args ? 'uninstall' : 'stop', 'purge $synopkgland_purge_args')
                 .replace(executor('purge $synopkgland_purge_args'), () => `synopkgland_uninstall_hook\n${executor('purge $synopkgland_purge_args')}`)
@@ -128,6 +128,25 @@ ${stop('stop', 'stop')}    ;;
 esac
 `;
 }
+const UPGRADE_STOP = "synopkgland_executor_upgrade_stop";
+/**
+ * preupgrade runs the outgoing package's helper: `stop --upgrade` lets the
+ * policy's stop step prepare the upgrade, and a helper from an SDK without
+ * the flag gets the plain stop it knows. Any other failure fails the hook.
+ */
+function renderExecutorUpgradeStop(pkg) {
+    const helper = `"\${SYNOPKG_PKGDEST:-/var/packages/${pkg}/target}/executor/lifecycle"`;
+    return `${UPGRADE_STOP}() {
+  synopkgland_stop_error=$(${helper} stop --package ${pkg} --upgrade 2>&1 >/dev/null) && return 0
+  synopkgland_stop_status=$?
+  case "$synopkgland_stop_error" in
+    *"flag provided but not defined: -upgrade"*) ${helper} stop --package ${pkg}; return $? ;;
+  esac
+  printf '%s\\n' "$synopkgland_stop_error" >&2
+  return "$synopkgland_stop_status"
+}
+`;
+}
 function renderDaemonScript(name, manifest) {
     const pkg = manifest.package;
     const control = `"/var/packages/${pkg}/target/daemon/control"`;