@synopackageland/cli 0.4.1 → 0.5.0

package/dist/init.js

@@ -1,6 +1,8 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, join, relative } from "node:path";
 import { templatesRoot } from "./template-paths.js";
+import { resolveMinDsm, assertContainerMinDsm, DEFAULT_MIN_DSM, isDsmAtLeast } from "./build-spk/dsm-version.js";
+import { readSharedFolder } from "./standalone/shared-folder.js";
 const TEMPLATE_NAMES = [
     "hello-web",
     "hello-web-page",
@@ -9,6 +11,17 @@ const TEMPLATE_NAMES = [
     "binary",
     "native-go",
 ];
+/** Templates whose App runs through the DSM docker-project resource worker. */
+const CONTAINER_TEMPLATES = [
+    "hello-web",
+    "hello-web-page",
+    "hello-files",
+    "compose-import",
+];
+/** The container templates need DSM 7.2.1 or later; native-go and binary need 7.1. */
+export function isContainerTemplate(template) {
+    return CONTAINER_TEMPLATES.includes(template);
+}
 export function isTemplateName(value) {
     return TEMPLATE_NAMES.includes(value);
 }
@@ -17,10 +30,14 @@ export function listTemplates() {
 }
 /**
  * native-go --privilege root: files laid over the native-go template, and the
- * files they replace.
+ * files they replace. An integration's helper brings its own root tasks, so
+ * the whoami example is not added to it.
  */
 const ROOT_OVERLAY = "native-go-root";
 const ROOT_REPLACED = ["backend/internal/app/root_none.go"];
+/** native-go --background: overlay with the routes, the UI panel and the docs. */
+const BACKGROUND_OVERLAY = "native-go-background";
+const BACKGROUND_REPLACED = ["backend/internal/app/background_none.go"];
 /** Templates whose identity is filled in at init (placeholders in these files). */
 const SUBSTITUTED = {
     "native-go": ["dsm-package.yaml", "README.md"],
@@ -42,22 +59,51 @@ function defaultDisplayName(dir) {
 function templateFiles(root, dir = root) {
     return readdirSync(dir).flatMap((name) => {
         const path = join(dir, name);
-        return statSync(path).isDirectory() ? templateFiles(root, path) : [relative(root, path)];
+        if (statSync(path).isDirectory()) {
+            return isTemplateBuildArtifact(path) ? [] : templateFiles(root, path);
+        }
+        return [relative(root, path)];
     });
 }
 function targetName(file) {
     return RENAMED[file] ?? file;
 }
+/** native-go defaults to the Vue shell; the CLI and the library entry point agree. */
+function resolvedUi(template, options) {
+    return template === "native-go" ? options.ui ?? "vue" : options.ui;
+}
+/**
+ * Copy one template tree into a project. A template directory may carry a local
+ * `node_modules`/`dist` from developing the template itself; those never belong
+ * to a generated project (and would otherwise shadow the project's own install).
+ */
+export function copyTemplateTree(source, target) {
+    cpSync(source, target, { recursive: true, filter: (path) => !isTemplateBuildArtifact(path) });
+}
+function isTemplateBuildArtifact(path) {
+    const name = basename(path);
+    return name === "node_modules" || name === "dist";
+}
 export function initFromTemplate(template, targetDir, options = {}) {
     const source = join(templatesRoot(), template);
     if (!existsSync(source)) {
         throw new Error(`找不到模板：${template}`);
     }
+    const minDsm = options.minDsm === undefined ? undefined : resolveMinDsm(options.minDsm);
+    if (minDsm !== undefined && isContainerTemplate(template)) {
+        assertContainerMinDsm(minDsm);
+    }
     const substitutions = substitutionsFor(template, targetDir, options);
-    const privilege = options.privilege ?? (options.integration ? "root" : "none");
+    const ui = resolvedUi(template, options);
+    const privilege = options.privilege ?? "none";
+    if (privilege === "root" && minDsm !== undefined && !isDsmAtLeast(minDsm, DEFAULT_MIN_DSM)) {
+        throw new Error(`[MIN_DSM_INVALID] root templates require DSM ${DEFAULT_MIN_DSM} or later.`);
+    }
+    const rootExample = privilege === "root" && !options.integration;
     const overlays = [
-        ...(privilege === "root" ? [ROOT_OVERLAY] : []),
-        ...(options.ui === "vue" ? ["native-go-vue"] : []),
+        ...(rootExample ? [ROOT_OVERLAY] : []),
+        ...(ui === "vue" ? ["native-go-vue"] : []),
+        ...(options.background ? [BACKGROUND_OVERLAY] : []),
         ...(options.integration ? ["native-go-integration"] : []),
         ...(options.integration === "better-auth" ? ["native-go-better-auth"] : []),
     ].map(name => join(templatesRoot(), name));
@@ -65,25 +111,27 @@ export function initFromTemplate(template, targetDir, options = {}) {
     // terms are an unconditional part of a generated project.
     const shared = join(templatesRoot(), "_shared");
     const files = [...templateFiles(source), "LICENSES/TEMPLATE.txt", ...overlays.flatMap(root => templateFiles(root)),
-        ...(options.ui === "vue" ? ["frontend/third-party-notices.mjs"] : []),
+        ...(ui === "vue" ? ["frontend/third-party-notices.mjs"] : []),
         ...(options.integration === "better-auth" ? ["node/third-party-notices.mjs", ...templateFiles(join(shared, 'notice-overrides')).map(file => `node/notice-overrides/${file}`)] : [])];
     const collisions = files.map(targetName).filter((file) => existsSync(join(targetDir, file)));
     if (collisions.length > 0) {
         throw new Error(`[INIT_TARGET_NOT_EMPTY] ${targetDir} 已有 ${collisions.join(", ")}；init 不會覆蓋既有檔案。請改用空目錄。`);
     }
     mkdirSync(targetDir, { recursive: true });
-    cpSync(source, targetDir, { recursive: true });
+    copyTemplateTree(source, targetDir);
     mkdirSync(join(targetDir, "LICENSES"), { recursive: true });
     cpSync(join(shared, "LICENSES/TEMPLATE.txt"), join(targetDir, "LICENSES/TEMPLATE.txt"));
     for (const overlay of overlays)
-        cpSync(overlay, targetDir, { recursive: true });
-    for (const dir of [...(options.ui === "vue" ? ["frontend"] : []), ...(options.integration === "better-auth" ? ["node"] : [])]) {
+        copyTemplateTree(overlay, targetDir);
+    for (const dir of [...(ui === "vue" ? ["frontend"] : []), ...(options.integration === "better-auth" ? ["node"] : [])]) {
         cpSync(join(shared, "third-party-notices.mjs"), join(targetDir, dir, "third-party-notices.mjs"));
     }
     if (options.integration === "better-auth")
         cpSync(join(shared, 'notice-overrides'), join(targetDir, 'node/notice-overrides'), { recursive: true });
-    if (privilege === "root")
+    if (rootExample)
         ROOT_REPLACED.forEach(file => rmSync(join(targetDir, file)));
+    if (options.background)
+        BACKGROUND_REPLACED.forEach(file => rmSync(join(targetDir, file)));
     for (const [from, to] of Object.entries(RENAMED)) {
         if (files.includes(from)) {
             renameSync(join(targetDir, from), join(targetDir, to));
@@ -97,11 +145,31 @@ export function initFromTemplate(template, targetDir, options = {}) {
         }
         writeFileSync(path, text);
     }
-    if (options.ui === "vue") {
+    if (minDsm) {
+        const manifest = join(targetDir, template === "native-go" ? "dsm-package.yaml" : "synology-app.yaml");
+        writeFileSync(manifest, readFileSync(manifest, "utf8").replace(/^os_min_ver:.*$/m, `os_min_ver: "${minDsm}"`));
+    }
+    if (ui === "vue") {
         const manifest = join(targetDir, "dsm-package.yaml");
         writeFileSync(manifest, readFileSync(manifest, "utf8").replace("  dir: ui", "  dir: frontend/dist\n  build: {cwd: frontend, command: [npm, run, build]}"));
         rmSync(join(targetDir, "ui"), { recursive: true });
     }
+    if (options.background) {
+        const manifest = join(targetDir, "dsm-package.yaml");
+        writeFileSync(manifest, readFileSync(manifest, "utf8") + "\nbackground:\n  worker: sha256-v1\n");
+        const app = join(targetDir, "frontend/src/App.vue");
+        writeFileSync(app, readFileSync(app, "utf8")
+            .replace("import NasUnavailable from './nas/NasUnavailable.vue'\n", "import NasUnavailable from './nas/NasUnavailable.vue'\nimport BackgroundPanel from './background/BackgroundPanel.vue'\n")
+            .replace("   <!-- BACKGROUND_PANEL -->", "   <BackgroundPanel v-if=\"app\" :key=\"app.user\" :ctx=\"ctx\" />"));
+    }
+    if (options.fileStation) {
+        const manifest = join(targetDir, "dsm-package.yaml");
+        writeFileSync(manifest, readFileSync(manifest, "utf8") + "\nfileStation: session\n");
+    }
+    if (options.sharedFolder) {
+        const manifest = join(targetDir, "dsm-package.yaml");
+        writeFileSync(manifest, readFileSync(manifest, "utf8") + sharedFolderYaml(options.sharedFolder));
+    }
     if (options.integration === "better-auth")
         rmSync(join(targetDir, "backend/internal/app/identity_none.go"));
     if (options.integration) {
@@ -113,12 +181,31 @@ export function initFromTemplate(template, targetDir, options = {}) {
         writeFileSync(routes, readFileSync(routes, "utf8").replace("return append(routes, cfg.rootRoutes()...)", "routes = append(routes, cfg.integrationRoutes()...)\n\treturn append(routes, cfg.rootRoutes()...)"));
     }
 }
+/** The `install.sharedFolder` block, validated by the same reader build-spk uses. */
+function sharedFolderYaml(options) {
+    const folder = { mode: options.mode, key: options.key ?? "shared", ...(options.name === undefined ? {} : { name: options.name }), permission: options.permission ?? "rw" };
+    const errors = [];
+    if (!readSharedFolder({ sharedFolder: folder }, e => errors.push(e.message))) {
+        throw new Error(`[INIT_SHARED_FOLDER_INVALID] ${errors.join(" ")}`);
+    }
+    return `\ninstall:\n  sharedFolder:\n${Object.entries(folder).map(([k, v]) => `    ${k}: ${v}\n`).join("")}`;
+}
 function substitutionsFor(template, targetDir, options) {
+    const ui = resolvedUi(template, options);
     if (options.privilege !== undefined && template !== "native-go") {
         throw new Error("[INIT_PRIVILEGE_UNSUPPORTED] --privilege 只適用於 -t native-go。");
     }
     if ((options.ui !== undefined || options.integration !== undefined) && template !== "native-go")
         throw new Error("[INIT_OPTIONS_UNSUPPORTED] --ui/--integration 只適用於 native-go。");
+    if (options.background && (template !== "native-go" || ui !== "vue" || options.privilege === "root" || options.integration === "better-auth"))
+        throw new Error("[INIT_BACKGROUND_OPTIONS] --background 只適用於 -t native-go 的 Vue UI（--ui vue，預設；--ui plain 不適用），且不能與 --privilege root 或 --integration better-auth 併用（背景 worker 只以套件帳號執行）；可與 --integration go、--file-station 併用。");
+    if (options.fileStation && (template !== "native-go" || (options.integration !== undefined && options.privilege === "root")))
+        throw new Error("[INIT_FILESTATION_OPTIONS] --file-station 只適用於 -t native-go，且不能與 --privilege root 的 --integration 並用（helper 有自己的 File Station gate）。");
+    if (options.sharedFolder) {
+        if (template !== "native-go")
+            throw new Error("[INIT_SHARED_FOLDER_INVALID] --shared-folder 只適用於 -t native-go。");
+        sharedFolderYaml(options.sharedFolder);
+    }
     if (options.ui !== undefined && !["plain", "vue"].includes(options.ui))
         throw new Error("[INIT_UI_INVALID] --ui 只接受 plain 或 vue。");
     if (options.integration !== undefined && !["go", "better-auth"].includes(options.integration))
@@ -127,9 +214,11 @@ function substitutionsFor(template, targetDir, options) {
         throw new Error("[INIT_DATA_ACCESS_INVALID] --data-access 只接受 unavailable 或 relaxed，且需要 --integration 與 --integration-protocol 2；缺少已認證 adapter 仍拒絕 NAS 操作。");
     if (options.integrationProtocol !== undefined && (!options.integration || ![1, 2].includes(options.integrationProtocol)))
         throw new Error("[INIT_INTEGRATION_PROTOCOL_INVALID] --integration-protocol 只接受 1 或 2，且需要 --integration；protocol 2 不啟用 NAS data path。");
-    if (options.integration && (options.ui !== "vue" || options.privilege === "none"))
-        throw new Error("[INIT_INTEGRATION_OPTIONS] integration 需要 --ui vue 與 root privilege（自動選用）。");
-    const privilege = options.privilege ?? (options.integration ? "root" : "none");
+    if (options.integration && ui !== "vue")
+        throw new Error("[INIT_INTEGRATION_OPTIONS] integration 需要 Vue UI（--ui vue，預設）；--ui plain 不適用。");
+    if (options.integration && options.privilege !== "root" && (options.integrationProtocol !== undefined || options.dataAccess !== undefined))
+        throw new Error("[INIT_INTEGRATION_HELPER_OPTIONS] --integration-protocol 與 --data-access 屬於 root helper，需要 --privilege root；沒有它時 integration 只以套件帳號執行，不含 helper。");
+    const privilege = options.privilege ?? "none";
     if (privilege !== "none" && privilege !== "root") {
         throw new Error(`[INIT_PRIVILEGE_INVALID] --privilege 只接受 none 或 root，收到「${String(privilege)}」。`);
     }
@@ -144,5 +233,5 @@ function substitutionsFor(template, targetDir, options) {
     if (displayName.trim() === "" || /[\r\n"\\]/.test(displayName)) {
         throw new Error("[INIT_DISPLAY_NAME_INVALID] 顯示名稱必須是單行，且不含 \" 或 \\。");
     }
-    return { __PACKAGE__: packageId, __DISPLAY_NAME__: displayName, __PRIVILEGE__: privilege };
+    return { __PACKAGE__: packageId, __DISPLAY_NAME__: displayName, __PRIVILEGE__: privilege, __BACKGROUND_ENABLED__: options.background ? "true" : "false" };
 }

package/dist/inspect.d.ts

@@ -1,3 +1,4 @@
+import { type PortExposure } from "./compose/analyze.js";
 import { type ProjectRoot } from "./discovery.js";
 export interface InspectReport {
     services: string[];
@@ -8,6 +9,8 @@ export interface InspectReport {
     dataMounts: string[];
     risks: string[];
     webHints: string[];
+    /** Ports reachable from outside the NAS without DSM authentication. */
+    exposedPorts: PortExposure[];
 }
 export declare function inspectProject(project: ProjectRoot): InspectReport;
 export declare function formatInspectReport(report: InspectReport): string;

package/dist/inspect.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { collectPublishedTcpPorts, listServiceNames, loadCompose, } from "./compose/analyze.js";
+import { collectPublishedTcpPorts, collectUnpinnedImages, listPortExposures, listServiceNames, loadCompose, } from "./compose/analyze.js";
 export function inspectProject(project) {
     const services = [];
     const publishedPorts = [];
@@ -13,11 +13,12 @@ export function inspectProject(project) {
             dataMounts,
             risks: ["缺少 compose.yaml"],
             webHints,
+            exposedPorts: [],
         };
     }
     const parsed = loadCompose(project.composePath);
     if (!parsed) {
-        return { services, publishedPorts, dataMounts, risks, webHints };
+        return { services, publishedPorts, dataMounts, risks, webHints, exposedPorts: [] };
     }
     const compose = parsed.compose;
     services.push(...listServiceNames(compose));
@@ -32,7 +33,8 @@ export function inspectProject(project) {
         webHints.push("Web App 通常還需要 adminprotocol 與 adminurl。");
         webHints.push("Launch Mode：integration.web.launch 為 dsm-window（預設，DSM 視窗）或 new-page（新分頁）。");
     }
-    return { services, publishedPorts, dataMounts, risks, webHints };
+    const exposedPorts = listPortExposures(compose).filter((exposure) => !exposure.loopbackOnly);
+    return { services, publishedPorts, dataMounts, risks, webHints, exposedPorts };
 }
 function collectDataMounts(compose, out) {
     if (!compose.services) {
@@ -51,6 +53,9 @@ function collectRisks(compose, out) {
     if (!compose.services) {
         return;
     }
+    for (const { service, image } of collectUnpinnedImages(compose)) {
+        out.push(`${service}: image ${image} is not pinned by digest (run \`synopkgland images pin\`; build-spk sets force_pull: true, so installs re-resolve the tag)`);
+    }
     for (const [serviceName, service] of Object.entries(compose.services)) {
         if (service.privileged) {
             out.push(`${serviceName}: privileged`);
@@ -96,6 +101,13 @@ export function formatInspectReport(report) {
     lines.push("Risk intents:");
     lines.push(report.risks.length > 0 ? report.risks.join("\n") : "(none)");
     lines.push("");
+    lines.push("Port exposure:");
+    lines.push(report.exposedPorts.length > 0
+        ? report.exposedPorts
+            .map((e) => `CONTAINER_PORT_EXPOSED ${e.service}: ${e.entry} 綁在所有網路介面，可不經 DSM 驗證直接連線；請改綁 127.0.0.1。`)
+            .join("\n")
+        : "(none)");
+    lines.push("");
     lines.push("Web entry hints:");
     lines.push(report.webHints.length > 0 ? report.webHints.join("\n") : "(none)");
     return lines.join("\n");

package/dist/standalone/background.d.ts

@@ -0,0 +1,21 @@
+import type { StandaloneError } from "./manifest.js";
+/**
+ * Opt-in package-private background jobs: DSM's official `systemd-user-unit`
+ * resource runs one fixed worker as the package account. There is no root,
+ * no root boot task and no process started from the CGI.
+ */
+export interface Background {
+    worker: "sha256-v1";
+}
+/** Payload path of the worker executable, relative to the package target. */
+export declare const BACKGROUND_WORKER_PAYLOAD = "background/worker";
+/** Go main package of the fixed worker inside the project's backend module. */
+export declare const BACKGROUND_WORKER_MAIN = "./cmd/background-worker";
+export declare const BACKGROUND_UNIT_DIR = "conf/systemd";
+export declare function backgroundUnitName(pkg: string): string;
+export declare function readBackground(value: unknown, fail: (error: StandaloneError) => void): Background | undefined;
+/** `conf/resource`: only the official user-unit resource. */
+export declare function renderBackgroundResource(): string;
+export declare function renderBackgroundUnit(pkg: string): string;
+/** Package Center's start/stop/status map straight onto the user unit. */
+export declare function renderBackgroundControl(pkg: string): string;

package/dist/standalone/background.js

@@ -0,0 +1,52 @@
+/** Payload path of the worker executable, relative to the package target. */
+export const BACKGROUND_WORKER_PAYLOAD = "background/worker";
+/** Go main package of the fixed worker inside the project's backend module. */
+export const BACKGROUND_WORKER_MAIN = "./cmd/background-worker";
+export const BACKGROUND_UNIT_DIR = "conf/systemd";
+const SYNOSYSTEMCTL = "/usr/syno/bin/synosystemctl";
+export function backgroundUnitName(pkg) {
+    return `pkguser-${pkg}-background.service`;
+}
+export function readBackground(value, fail) {
+    if (value === undefined)
+        return undefined;
+    const ok = typeof value === "object" && value !== null && !Array.isArray(value)
+        && Object.keys(value).length === 1 && value.worker === "sha256-v1";
+    if (!ok) {
+        fail({ code: "STANDALONE_BACKGROUND_INVALID", message: "background 只接受 { worker: sha256-v1 }；背景程序固定以套件帳號執行，不能指定使用者、指令或權限。" });
+        return undefined;
+    }
+    return { worker: "sha256-v1" };
+}
+/** `conf/resource`: only the official user-unit resource. */
+export function renderBackgroundResource() {
+    return JSON.stringify({ "systemd-user-unit": {} });
+}
+export function renderBackgroundUnit(pkg) {
+    return `[Unit]
+Description=${pkg} background worker
+
+[Service]
+Type=simple
+ExecStart=/var/packages/${pkg}/target/${BACKGROUND_WORKER_PAYLOAD}
+UMask=0077
+KillMode=control-group
+TimeoutStopSec=10
+Restart=no
+`;
+}
+/** Package Center's start/stop/status map straight onto the user unit. */
+export function renderBackgroundControl(pkg) {
+    const unit = backgroundUnitName(pkg);
+    return `#!/bin/sh
+case "$1" in
+  start) exec ${SYNOSYSTEMCTL} start ${unit} ;;
+  stop) exec ${SYNOSYSTEMCTL} stop ${unit} ;;
+  status)
+    [ "$(${SYNOSYSTEMCTL} get-active-status ${unit})" = active ] && exit 0
+    exit 3
+    ;;
+  *) exit 1 ;;
+esac
+`;
+}

package/dist/standalone/binary.d.ts

@@ -1,5 +1,6 @@
 import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
 import type { StandaloneError } from "./manifest.js";
+export declare const ELF_MACHINE: Record<NativeArchFamily, number>;
 /**
  * Checks a prebuilt CGI before it is packaged: a regular file inside the
  * project, a 64-bit little-endian ELF for `arch`, and statically linked

package/dist/standalone/binary.js

@@ -1,6 +1,6 @@
 import { closeSync, lstatSync, openSync, readSync, realpathSync } from "node:fs";
 import { relative } from "node:path";
-const ELF_MACHINE = { x86_64: 62, aarch64: 183 };
+export const ELF_MACHINE = { x86_64: 62, aarch64: 183 };
 const PT_INTERP = 3;
 const MAX_BINARY_BYTES = 256 * 1024 * 1024;
 const HEADER_BYTES = 64 * 1024;

package/dist/standalone/build.d.ts

@@ -15,6 +15,8 @@ export interface StandaloneBuildOptions {
     arches?: NativeArchFamily[];
     /** Defaults to `<root>/dist`. */
     outDir?: string;
+    /** INFO os_min_ver for every SPK (a release such as 7.1, or a full 7.x-build); defaults to the manifest's. */
+    minDsm?: string;
     run?: CommandRunner;
 }
 /** Argv only, never a shell; output streams to the terminal except stderr, which is also kept. */

package/dist/standalone/build.js

@@ -1,12 +1,14 @@
 import { spawnSync } from "node:child_process";
-import { mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { resolveMinDsm, DEFAULT_MIN_DSM, isDsmAtLeast } from "../build-spk/dsm-version.js";
 import { checkCgiBinary } from "./binary.js";
 import { loadStandaloneManifest } from "./manifest.js";
 import { assembleStandaloneSpk, StandaloneBuildError } from "./spk.js";
 import { buildHelper } from "./helper.js";
 import { buildDaemonControl } from "./daemon.js";
+import { BACKGROUND_WORKER_MAIN } from "./background.js";
 const GOARCH = { x86_64: "amd64", aarch64: "arm64" };
 /** Argv only, never a shell; output streams to the terminal except stderr, which is also kept. */
 export const runCommand = (command, args, options) => {
@@ -29,7 +31,12 @@ export async function buildStandalone(options) {
         const [first] = loaded.errors;
         throw new StandaloneBuildError(first.code, loaded.errors.map((e) => `[${e.code}] ${e.message}`).join("\n"));
     }
-    const manifest = loaded.manifest;
+    const manifest = options.minDsm === undefined
+        ? loaded.manifest
+        : { ...loaded.manifest, os_min_ver: resolveMinDsm(options.minDsm) };
+    if (manifest.privilege === "root" && !isDsmAtLeast(manifest.os_min_ver, DEFAULT_MIN_DSM)) {
+        throw new StandaloneBuildError("STANDALONE_OS_MIN_VER_INVALID", `root templates require DSM ${DEFAULT_MIN_DSM} or later.`);
+    }
     const run = options.run ?? runCommand;
     const arches = options.arches ?? manifest.arches;
     for (const arch of arches) {
@@ -62,7 +69,8 @@ export async function buildStandalone(options) {
             const outputPath = join(outDir, `${manifest.package}-${manifest.spkVersion}-${arch}.spk`);
             const daemonControl = buildDaemonControl(manifest, arch, work, run);
             const builtManifest = helper ? { ...manifest, rootOps: [...(manifest.rootOps ?? []), ...helper.ops] } : manifest;
-            await assembleStandaloneSpk({ manifest: builtManifest, arch, cgiPath, outputPath, helper, daemonControl });
+            const backgroundWorker = buildBackgroundWorker(manifest, arch, work, run);
+            await assembleStandaloneSpk({ manifest: builtManifest, arch, cgiPath, outputPath, helper, daemonControl, backgroundWorker });
             outputs.push(outputPath);
         }
         return { outputs };
@@ -77,9 +85,12 @@ function buildUi(manifest, run) {
         return;
     }
     const [command, ...args] = build.command;
-    const result = run(command, args, { cwd: build.cwd, env: { ...process.env } });
+    const result = run(command, args, { cwd: build.cwd, env: { ...process.env, SYNOPKGLAND_SDK_WORKERS: manifest.integration?.sdkWorkers ? "1" : "0" } });
     if (result.missing || result.status !== 0) {
-        throw new StandaloneBuildError("STANDALONE_UI_BUILD_FAILED", `UI build（${build.command.join(" ")}）失敗。\n${result.stderr}`);
+        const installHint = command === "npm" && existsSync(join(build.cwd, "package.json")) && !existsSync(join(build.cwd, "node_modules"))
+            ? `\nUI 依賴尚未安裝。請在 ${build.cwd} 執行 npm ${existsSync(join(build.cwd, "package-lock.json")) ? "ci" : "install"}，然後重新執行 build-spk。`
+            : "";
+        throw new StandaloneBuildError("STANDALONE_UI_BUILD_FAILED", `UI build（${build.command.join(" ")}）失敗。${installHint}\n${result.stderr}`);
     }
 }
 function backendFor(manifest, arch, work, run, helper) {
@@ -95,8 +106,11 @@ function backendFor(manifest, arch, work, run, helper) {
         `-X main.packageID=${manifest.package}`,
         `-X main.version=${manifest.spkVersion}`,
         ...(helper ? [`-X 'main.helperInventory=${JSON.stringify(helper.inventory)}'`] : []),
+        // Integration without a helper: the CGI serves its package-account features itself.
+        ...(manifest.integration && !helper ? ["-X main.integrationMode=package"] : []),
+        ...(manifest.fileStation ? [`-X main.fileStation=${manifest.fileStation}`] : []),
     ].join(" ");
-    const result = run("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, backend.main], {
+    const result = run("go", ["build", ...(manifest.integration?.sdkWorkers ? ["-tags=synopkgland_sdk_workers"] : []), "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, backend.main], {
         cwd: backend.dir,
         env: { ...process.env, CGO_ENABLED: "0", GOOS: "linux", GOARCH: GOARCH[arch] },
     });
@@ -108,3 +122,21 @@ function backendFor(manifest, arch, work, run, helper) {
     }
     return out;
 }
+/** The fixed worker is a second binary of the project's own Go module. */
+function buildBackgroundWorker(manifest, arch, work, run) {
+    if (!manifest.background || manifest.backend.kind !== "go")
+        return undefined;
+    const out = join(work, `background-worker-${arch}`);
+    const ldflags = ["-s", "-w", "-buildid=", `-X main.packageID=${manifest.package}`].join(" ");
+    const result = run("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, BACKGROUND_WORKER_MAIN], {
+        cwd: manifest.backend.dir,
+        env: { ...process.env, CGO_ENABLED: "0", GOOS: "linux", GOARCH: GOARCH[arch] },
+    });
+    if (result.missing || result.status !== 0) {
+        throw new StandaloneBuildError("STANDALONE_BACKGROUND_BUILD_FAILED", `background worker（${BACKGROUND_WORKER_MAIN}）build 失敗；這個專案的 backend 需要含該 package。\n${result.stderr}`);
+    }
+    const problem = checkCgiBinary(work, out, arch);
+    if (problem)
+        throw new StandaloneBuildError(problem.code, problem.message);
+    return out;
+}

package/dist/standalone/dsm-window.js

@@ -273,8 +273,8 @@ ${ROOT_PANEL}
       confirmPassword: function () {
         return new Promise(function (resolve) {
           SYNO.SDS.Utils.PasswordConfirmDialog.openDialog(me, function (confirmation) {
-            resolve((confirmation && confirmation.SynoConfirmPWToken) || null);
-          }, [], function () { resolve(null); });
+            resolve({ confirmed: true, token: (confirmation && confirmation.SynoConfirmPWToken) || null });
+          }, [], function () { resolve({ confirmed: false, token: null }); });
         });
       },
       call: ${ns}.call,

package/dist/standalone/helper-inventory.d.ts

@@ -1,9 +1,11 @@
+import type { SDKWorkerConfig } from "./worker-registry.js";
 export type DataAccessMode = "unavailable" | "relaxed";
 export interface Integration {
     protocol: 1 | 2;
     workers: Record<string, string>;
     identity?: "better-auth";
     dataAccess?: DataAccessMode;
+    sdkWorkers?: Record<string, SDKWorkerConfig>;
 }
 export interface HelperInventory {
     package: string;
@@ -13,4 +15,17 @@ export interface HelperInventory {
     registryDigest: string;
     dataAccess?: DataAccessMode;
 }
+/**
+ * The privileged helper exists only for an integration that also declares
+ * privilege: root. Without it, integration is package-account only.
+ */
+export declare const hasHelper: (m: {
+    integration?: unknown;
+    privilege?: "none" | "root";
+}) => boolean;
 export declare const sha256: (b: string | Buffer) => string;
+/** Preserve the original inert inventory byte format, including property order. */
+export declare function inertWorkerRegistry(workers: readonly {
+    id: string;
+    digest: string;
+}[]): string;

package/dist/standalone/helper-inventory.js

@@ -1,2 +1,11 @@
 import { createHash } from "node:crypto";
+/**
+ * The privileged helper exists only for an integration that also declares
+ * privilege: root. Without it, integration is package-account only.
+ */
+export const hasHelper = (m) => m.integration !== undefined && m.privilege === "root";
 export const sha256 = (b) => createHash("sha256").update(b).digest("hex");
+/** Preserve the original inert inventory byte format, including property order. */
+export function inertWorkerRegistry(workers) {
+    return JSON.stringify(workers.map(({ id, digest }) => ({ id, digest })));
+}

package/dist/standalone/helper.d.ts

@@ -13,6 +13,7 @@ export interface HelperArtifact {
     binary: string;
     inventory: HelperInventory;
     workers: WorkerPayload[];
+    registry?: string;
     ops: RootOp[];
 }
 export declare function readIntegration(raw: unknown, root: string, fail: (e: StandaloneError) => void): Integration | undefined;

package/dist/standalone/helper.js

@@ -2,13 +2,14 @@ import { lstatSync, readFileSync, realpathSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { renderRootTaskScript } from "./root-ops.js";
 import { StandaloneBuildError } from "./spk.js";
-import { sha256 } from "./helper-inventory.js";
+import { hasHelper, sha256 } from "./helper-inventory.js";
+import { buildWorkerRegistry, parseSDKWorkers } from "./worker-registry.js";
 const record = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 export function readIntegration(raw, root, fail) {
     if (raw === undefined)
         return undefined;
-    const invalid = () => { fail({ code: "STANDALONE_INTEGRATION_INVALID", message: "integration 需要 protocol: 1 或 2 與 workers: {固定 ID: 專案內檔案}；最多 16 個，僅作 inventory，不執行 worker。" }); return undefined; };
-    if (!record(raw) || Object.keys(raw).some(k => !["protocol", "workers", "identity", "dataAccess"].includes(k)) || ![1, 2].includes(raw.protocol) || !record(raw.workers) || Object.keys(raw.workers).length > 16)
+    const invalid = () => { fail({ code: "STANDALONE_INTEGRATION_INVALID", message: "integration 需要 protocol: 1 或 2 與 inert workers；sdkWorkers 僅接受 protocol 2／relaxed 的固定 SDK kind、action/mode 與較低 limits。總數最多 16，production unavailable。" }); return undefined; };
+    if (!record(raw) || Object.keys(raw).some(k => !["protocol", "workers", "identity", "dataAccess", "sdkWorkers"].includes(k)) || ![1, 2].includes(raw.protocol) || !record(raw.workers) || Object.keys(raw.workers).length > 16)
         return invalid();
     if (raw.identity !== undefined && raw.identity !== "better-auth")
         return invalid();
@@ -23,7 +24,18 @@ export function readIntegration(raw, root, fail) {
             return invalid();
         workers[id] = path;
     }
-    return { protocol: raw.protocol, workers, ...(raw.identity === "better-auth" ? { identity: "better-auth" } : {}), ...(raw.dataAccess !== undefined ? { dataAccess: raw.dataAccess } : {}) };
+    let sdkWorkers;
+    if (Object.hasOwn(raw, "sdkWorkers")) {
+        if (raw.protocol !== 2 || raw.dataAccess !== "relaxed")
+            return invalid();
+        try {
+            sdkWorkers = parseSDKWorkers(raw.sdkWorkers, Object.keys(workers));
+        }
+        catch {
+            return invalid();
+        }
+    }
+    return { protocol: raw.protocol, workers, ...(raw.identity === "better-auth" ? { identity: "better-auth" } : {}), ...(raw.dataAccess !== undefined ? { dataAccess: raw.dataAccess } : {}), ...(sdkWorkers ? { sdkWorkers } : {}) };
 }
 function snapshotWorkers(m) {
     let total = 0;
@@ -87,19 +99,25 @@ exec "$exe" ${action}
     });
 }
 export function buildHelper(m, arch, work, run) {
-    if (!m.integration)
+    if (!m.integration || !hasHelper(m))
         return undefined;
     if (m.backend.kind !== "go")
         throw new StandaloneBuildError("HELPER_GO_REQUIRED", "M1a integration 僅支援 native-go。");
     const workers = snapshotWorkers(m);
-    const registry = workers.map(({ id, digest }) => ({ id, digest }));
-    const base = { package: m.package, version: m.spkVersion, protocol: m.integration.protocol, payloadDigest: "", registryDigest: sha256(JSON.stringify(registry)), ...(m.integration.dataAccess ? { dataAccess: m.integration.dataAccess } : {}) };
+    const registry = buildWorkerRegistry(workers, m.integration.sdkWorkers, m.backend.dir);
+    const base = { package: m.package, version: m.spkVersion, protocol: m.integration.protocol, payloadDigest: "", registryDigest: sha256(registry), ...(m.integration.dataAccess ? { dataAccess: m.integration.dataAccess } : {}) };
     const binary = join(work, `helper-${arch}`);
-    const result = run("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", `-s -w -buildid= -X 'main.helperInventory=${JSON.stringify(base)}'`, "-o", binary, "./cmd/helper"], {
+    const sdkFlags = m.integration.sdkWorkers ? ["-tags=synopkgland_sdk_workers"] : [];
+    const sdkBinding = m.integration.sdkWorkers ? ` -X 'main.sdkWorkerRegistry=${registry}'` : "";
+    const result = run("go", ["build", ...sdkFlags, "-trimpath", "-buildvcs=false", "-ldflags", `-s -w -buildid= -X 'main.helperInventory=${JSON.stringify(base)}'${sdkBinding}`, "-o", binary, "./cmd/helper"], {
         cwd: m.backend.dir, env: { ...process.env, CGO_ENABLED: "0", GOOS: "linux", GOARCH: arch === "x86_64" ? "amd64" : "arm64" },
     });
     if (result.missing || result.status !== 0)
         throw new StandaloneBuildError("HELPER_BUILD_FAILED", `Go helper build 失敗：${result.stderr}`);
-    const inventory = { ...base, payloadDigest: sha256(readFileSync(binary)) };
-    return { binary, inventory, workers, ops: helperOps(m, inventory) };
+    const payload = readFileSync(binary);
+    if (m.integration.sdkWorkers && (!payload.includes(Buffer.from(registry)) || buildWorkerRegistry(workers, m.integration.sdkWorkers, m.backend.dir) !== registry)) {
+        throw new StandaloneBuildError("HELPER_BUILD_FAILED", "compiled SDK registry 缺失或 source 在建置期間變動；請用完整 SDK 模板重新建置。");
+    }
+    const inventory = { ...base, payloadDigest: sha256(payload) };
+    return { binary, inventory, workers, ...(m.integration.sdkWorkers ? { registry } : {}), ops: helperOps(m, inventory) };
 }