@synopackageland/cli 0.4.0 → 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, dirname, join, relative } from "node:path";
-import { fileURLToPath } from "node:url";
+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,26 +11,33 @@ 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);
 }
 export function listTemplates() {
     return [...TEMPLATE_NAMES];
 }
-function templatesRoot() {
-    const moduleDir = dirname(fileURLToPath(import.meta.url));
-    const distTemplates = join(moduleDir, "templates");
-    if (existsSync(distTemplates)) {
-        return distTemplates;
-    }
-    return join(moduleDir, "..", "templates");
-}
 /**
  * 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"],
@@ -50,36 +59,79 @@ 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));
-    const files = [...templateFiles(source), ...overlays.flatMap(root => templateFiles(root))];
+    // Shared legal resources also live in the CLI package; only the template
+    // 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)),
+        ...(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 });
-    if (privilege === "root")
+        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 (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));
@@ -93,35 +145,80 @@ 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) {
         const mod = join(targetDir, "backend/go.mod");
         writeFileSync(mod, readFileSync(mod, "utf8").replace("go 1.24", "go 1.25"));
         const manifest = join(targetDir, "dsm-package.yaml");
-        writeFileSync(manifest, readFileSync(manifest, "utf8") + "\nintegration:\n  protocol: 1\n  workers: {}\n" + (options.integration === "better-auth" ? "  identity: better-auth\n" : ""));
+        writeFileSync(manifest, readFileSync(manifest, "utf8") + `\nintegration:\n  protocol: ${options.integrationProtocol ?? 1}\n  workers: {}\n` + (options.integration === "better-auth" ? "  identity: better-auth\n" : "") + (options.dataAccess ? `  dataAccess: ${options.dataAccess}\n` : ""));
         const routes = join(targetDir, "backend/internal/app/routes.go");
         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))
         throw new Error("[INIT_INTEGRATION_INVALID] --integration 只接受 go 或 better-auth。");
-    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.dataAccess !== undefined && (!options.integration || options.integrationProtocol !== 2 || !["unavailable", "relaxed"].includes(options.dataAccess)))
+        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 && 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)}」。`);
     }
@@ -136,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,11 +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) => {
@@ -28,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) {
@@ -59,8 +67,10 @@ export async function buildStandalone(options) {
                 throw new StandaloneBuildError(problem.code, problem.message);
             }
             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 });
+            const backgroundWorker = buildBackgroundWorker(manifest, arch, work, run);
+            await assembleStandaloneSpk({ manifest: builtManifest, arch, cgiPath, outputPath, helper, daemonControl, backgroundWorker });
             outputs.push(outputPath);
         }
         return { outputs };
@@ -75,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) {
@@ -93,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] },
     });
@@ -106,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/daemon.d.ts

@@ -0,0 +1,23 @@
+import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
+import type { CommandRunner } from "./build.js";
+import type { StandaloneError, StandaloneManifest } from "./manifest.js";
+export interface Daemon {
+    /** Fixed foreground executable relative to daemon/payload. */
+    exec: string;
+    /** Architecture-specific project directories, copied without links. */
+    targets: Partial<Record<NativeArchFamily, string>>;
+    args: string[];
+    /** Optional fixed executable argv, after stop, only on uninstall. */
+    uninstall_args?: string[];
+    /** The only application environment inherited beyond PATH/HOME/TMPDIR. */
+    env: Record<string, string>;
+    timeouts: {
+        start: number;
+        stop: number;
+        status: number;
+    };
+}
+export declare function readDaemon(value: unknown, root: string, arches: NativeArchFamily[], fail: (error: StandaloneError) => void): Daemon | undefined;
+export declare function daemonConfig(manifest: StandaloneManifest): string;
+export declare function buildDaemonControl(manifest: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner): string | undefined;
+export declare function copyDaemonPayload(manifest: StandaloneManifest, arch: NativeArchFamily, target: string, controller: string): void;

package/dist/standalone/daemon.js

@@ -0,0 +1,114 @@
+import { chmodSync, copyFileSync, lstatSync, mkdirSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { templatesRoot } from "../template-paths.js";
+import { checkCgiBinary } from "./binary.js";
+import { StandaloneBuildError } from "./spk.js";
+const fields = new Set(["exec", "targets", "args", "env", "timeouts", "uninstall_args"]);
+const record = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+const token = (v) => typeof v === "string" && Buffer.byteLength(v) <= 4096 && !v.includes("\0")
+    && !v.replaceAll("${SYNOPKG_PKGDEST}", "").replaceAll("${SYNOPKG_PKGVAR}", "").includes("${");
+const envKey = (k) => /^[A-Z][A-Z0-9_]{0,63}$/.test(k)
+    && !/^(PATH|HOME|TMPDIR|ENV|BASH_ENV|SHELLOPTS|BASHOPTS|GODEBUG|GOTRACEBACK|LD_.*|DYLD_.*|SYNOPKG_.*)$/.test(k);
+export function readDaemon(value, root, arches, fail) {
+    if (value === undefined)
+        return undefined;
+    const invalid = () => { fail({ code: "STANDALONE_DAEMON_INVALID", message: "daemon 只接受固定 exec、targets、args、env 與 timeouts；路徑須在專案內，環境不接受 loader/shell/system 變數。" }); return undefined; };
+    if (!record(value) || Object.keys(value).some(k => !fields.has(k)))
+        return invalid();
+    if (typeof value.exec !== "string" || !/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(value.exec)
+        || value.exec.split("/").some(p => p === "." || p === "..") || value.exec.length > 200)
+        return invalid();
+    if (!record(value.targets) || Object.keys(value.targets).length !== arches.length)
+        return invalid();
+    const targets = {};
+    for (const arch of arches) {
+        const path = value.targets[arch];
+        if (typeof path !== "string" || !path.trim() || path.includes("\0") || isAbsolute(path) || path.split(/[\\/]/).includes(".."))
+            return invalid();
+        const resolved = resolve(root, path), rel = relative(root, resolved);
+        if (!rel || rel.startsWith("..") || isAbsolute(rel))
+            return invalid();
+        targets[arch] = resolved;
+    }
+    const args = value.args ?? [];
+    if (!Array.isArray(args) || args.length > 64 || !args.every(token))
+        return invalid();
+    const uninstall = value.uninstall_args;
+    if (uninstall !== undefined && (!Array.isArray(uninstall) || !uninstall.length || uninstall.length > 64 || !uninstall.every(token)))
+        return invalid();
+    const env = value.env ?? {};
+    if (!record(env) || Object.keys(env).length > 64 || Object.entries(env).some(([k, v]) => !envKey(k) || !token(v)))
+        return invalid();
+    const limits = value.timeouts ?? {};
+    if (!record(limits) || Object.keys(limits).some(k => !["start", "stop", "status"].includes(k)))
+        return invalid();
+    const timeouts = { start: limits.start ?? 5, stop: limits.stop ?? 10, status: limits.status ?? 2 };
+    for (const [key, v] of Object.entries(timeouts)) {
+        if (!Number.isInteger(v) || v < (key === "start" ? 2 : key === "stop" ? 2 : 1) || v > (key === "status" ? 10 : 120))
+            return invalid();
+    }
+    return { exec: value.exec, targets, args, ...(uninstall ? { uninstall_args: uninstall } : {}), env: Object.fromEntries(Object.keys(env).sort().map(key => [key, env[key]])), timeouts: timeouts };
+}
+export function daemonConfig(manifest) {
+    const { exec, args, uninstall_args, env, timeouts } = manifest.daemon;
+    return JSON.stringify({ package: manifest.package, exec, args, ...(uninstall_args ? { uninstall_args } : {}), env, timeouts }) + "\n";
+}
+export function buildDaemonControl(manifest, arch, work, run) {
+    if (!manifest.daemon)
+        return undefined;
+    const out = join(work, `daemon-control-${arch}`);
+    const result = run("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", "-s -w -buildid=", "-o", out, "."], {
+        cwd: join(templatesRoot(), "_daemon"), env: { ...process.env, CGO_ENABLED: "0", GOOS: "linux", GOARCH: arch === "x86_64" ? "amd64" : "arm64" },
+    });
+    if (result.missing || result.status !== 0)
+        throw new StandaloneBuildError("STANDALONE_DAEMON_BUILD_FAILED", `daemon controller build 需要 Go 1.24 以上。\n${result.stderr}`);
+    const problem = checkCgiBinary(work, out, arch);
+    if (problem)
+        throw new StandaloneBuildError(problem.code, problem.message);
+    return out;
+}
+export function copyDaemonPayload(manifest, arch, target, controller) {
+    const daemon = manifest.daemon;
+    const source = daemon.targets[arch];
+    const invalid = (message) => { throw new StandaloneBuildError("STANDALONE_DAEMON_PAYLOAD_INVALID", message); };
+    let total = 0;
+    const walk = (from, to) => {
+        const stat = lstatSync(from);
+        const rel = relative(realpathSync(manifest.root), realpathSync(from));
+        if (rel.startsWith("..") || isAbsolute(rel) || stat.isSymbolicLink())
+            invalid(`daemon payload 路徑不可含 symlink 或跳出專案：${from}`);
+        if (stat.isDirectory()) {
+            mkdirSync(to, { recursive: true });
+            chmodSync(to, 0o755);
+            for (const name of readdirSync(from).sort())
+                walk(join(from, name), join(to, name));
+        }
+        else if (stat.isFile()) {
+            total += stat.size;
+            if (total > 512 * 1024 * 1024 || (stat.mode & 0o6000))
+                invalid(`daemon payload 不接受 setid 或超過 512 MiB：${from}`);
+            copyFileSync(from, to);
+            chmodSync(to, stat.mode & 0o111 ? 0o755 : 0o644);
+        }
+        else
+            invalid(`daemon payload 只接受一般檔案及目錄：${from}`);
+    };
+    try {
+        if (!lstatSync(source).isDirectory())
+            invalid("daemon.targets 必須指向目錄。");
+        walk(source, join(target, "payload"));
+    }
+    catch (error) {
+        if (error instanceof StandaloneBuildError)
+            throw error;
+        invalid(`無法讀取 daemon payload：${String(error)}`);
+    }
+    const exec = join(source, daemon.exec);
+    const problem = checkCgiBinary(manifest.root, exec, arch);
+    if (problem)
+        throw new StandaloneBuildError(problem.code, problem.message);
+    chmodSync(join(target, "payload", daemon.exec), 0o755);
+    copyFileSync(controller, join(target, "control"));
+    chmodSync(join(target, "control"), 0o755);
+    writeFileSync(join(target, "config.json"), daemonConfig(manifest), { mode: 0o644 });
+}