@synopackageland/cli 0.5.0 → 0.6.0

package/dist/standalone/inspect-spk.js

@@ -1,3 +1,4 @@
+import { inspectExecutor } from "../runtime/executor-inspect.js";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -7,14 +8,14 @@ import { CONTAINER_MIN_DSM, isDsmAtLeast } from "../build-spk/dsm-version.js";
 import { ELF_MACHINE } from "./binary.js";
 import { CGI_PAYLOAD_PATH } from "./dsm-window.js";
 import { daemonConfig, readDaemon } from "./daemon.js";
-import { BACKGROUND_UNIT_DIR, BACKGROUND_WORKER_PAYLOAD, backgroundUnitName, renderBackgroundControl, renderBackgroundUnit } from "./background.js";
+import { BACKGROUND_UNIT_DIR, BACKGROUND_WORKER_PAYLOAD, 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";
+import { renderUninstallWizardFiles } from "../build-spk/uninstall-wizard.js";
 import { renderStandaloneScript } from "./lifecycle.js";
 import { listPortExposures, loadCompose } from "../compose/analyze.js";
-import { inspectHelper } from "./inspect-helper.js";
-import { inspectNativeLayout } from "./native-layout.js";
+import { uninstallCleanup } from "../runtime/uninstall-cleanup.js";
 const ROOT_SCRIPT_HINTS = [/\bsudo\b/, /\bchown\s+(-\w+\s+)*root\b/, /chmod\s+[ugo]*\+s\b/, /chmod\s+[2467][0-7]{3}\b/];
 /** Reads an SPK without installing it and reports how it would run on DSM. */
 export async function inspectStandaloneSpk(spkPath) {
@@ -26,59 +27,66 @@ export async function inspectSpk(spkPath, expectedKind) {
     try {
         await tar.x({ file: spkPath, cwd: dir });
         const findings = [];
-        if (!expectedKind && existsSync(join(dir, "native-layout.json"))) {
-            const findings = [];
-            const info = Object.fromEntries(readFileSync(join(dir, "INFO"), "utf8").split("\n").flatMap(line => {
-                const m = line.match(/^([a-z_]+)="([^"\r\n]*)"$/);
-                return m ? [[m[1], m[2]]] : [];
-            }));
-            const payload = await listPayload(join(dir, "package.tgz"), findings);
-            const target = join(dir, "layout-inspection");
-            mkdirSync(target);
-            await tar.x({ file: join(dir, "package.tgz"), cwd: target });
-            findings.push(...inspectNativeLayout(dir, target, info));
-            for (const key of ["package", "version", "arch", "os_min_ver", "checksum"])
-                if (!info[key])
-                    findings.push(`Missing INFO ${key}`);
-            return { kind: "native-layout", package: info.package, version: info.version, arch: info.arch, signed: existsSync(join(dir, "syno_signature.asc")), payload, findings };
-        }
         const payload = await listPayload(join(dir, "package.tgz"), findings);
         const paths = new Set(payload.map(entry => entry.path));
-        const kind = expectedKind ?? (paths.has(CGI_PAYLOAD_PATH) ? "native-go"
-            : paths.has("native.yaml") ? "binary" : paths.has("compose.yaml") ? "container" : "native-go");
-        const helperPayload = ["integration/helper", "integration/inventory.json", "integration/workers.json"].every(path => paths.has(path));
-        const identityPayload = [CGI_PAYLOAD_PATH, "integration/identity/app.mjs"].every(path => paths.has(path)) && (helperPayload || !paths.has("integration/helper"));
-        const info = readInfo(join(dir, "INFO"), findings, kind, identityPayload);
-        if (kind === "native-go" && paths.has("integration/helper") && info.precheckstartstop !== "yes") {
-            findings.push('integration INFO 必須明確設定 precheckstartstop="yes"，否則 DSM 不執行 prestop');
+        let metadata = {};
+        const metadataText = readOptional(join(dir, "sdk-package.json"));
+        if (metadataText !== undefined) {
+            try {
+                const raw = JSON.parse(metadataText);
+                if (raw.schema !== 2 || !["go", "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)
+                    throw new Error();
+                metadata = raw;
+            }
+            catch {
+                findings.push("sdk-package.json 不符合 schema 2 capability inventory。");
+            }
         }
+        const binaryBackend = metadata.backend === "binary";
+        const kind = expectedKind ?? (paths.has("compose.yaml") ? "container" : binaryBackend ? "binary" : "native-go");
+        const standalone = kind === "native-go" || kind === "binary";
+        const info = readInfo(join(dir, "INFO"), findings, kind);
         await checkArch(dir, info, kind, paths.has(CGI_PAYLOAD_PATH), findings);
         const background = kind === "native-go" && paths.has(BACKGROUND_WORKER_PAYLOAD);
-        const sharedFolder = kind === "native-go" ? recoverSharedFolder(readOptional(join(dir, "scripts/postinst"))) : undefined;
+        const sharedFolder = standalone ? recoverSharedFolder(readOptional(join(dir, "scripts/postinst"))) : undefined;
         checkConf(dir, findings, kind, background, sharedFolder, info.package);
         checkScripts(dir, findings);
-        if (kind === "native-go")
+        if (standalone)
             checkSharedFolder(dir, findings, info.package, sharedFolder);
         checkUninstall(dir, findings);
         if (kind === "container")
             await checkContainerExposure(dir, join(dir, "package.tgz"), findings);
+        const hasExecutor = (metadata.capabilities ?? []).some(name => name === "rootOps" || name === "delegate") || paths.has("executor/executor");
         if (background)
-            checkBackground(dir, info, payload, findings);
-        if (kind === "native-go")
-            await checkDaemon(dir, info, paths, payload, findings);
-        let integration;
-        const integrationPaths = [...paths].filter(path => path.startsWith("integration/"));
-        if (integrationPaths.length > 0 && paths.has("integration/helper")) {
-            if (kind !== "native-go" || payload.find(p => p.path === "integration/helper")?.mode !== "0755")
-                findings.push("integration 必須有 native-go executable helper");
-            else if (!findings.length)
-                integration = await inspectHelper(dir, info, findings, paths.has("daemon/config.json"));
-        }
-        else if (integrationPaths.some(path => path !== "integration/identity/app.mjs")) {
-            findings.push("integration 沒有 helper 時只可附 integration/identity/app.mjs");
+            checkBackground(dir, info, payload, findings, hasExecutor);
+        if (standalone)
+            await checkDaemon(dir, info, paths, payload, findings, hasExecutor);
+        let executor;
+        if ((metadata.capabilities ?? []).some(name => name === "rootOps" || name === "delegate") || paths.has("executor/executor")) {
+            const executorDir = join(dir, "executor-inspection");
+            mkdirSync(executorDir);
+            await tar.x({ file: join(dir, "package.tgz"), cwd: executorDir });
+            const inspected = inspectExecutor(executorDir, info.package, info.arch);
+            findings.push(...inspected.findings);
+            executor = inspected.executor;
+            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")
+                findings.push("Executor lifecycle helper must be executable.");
+            if (![...paths].some(path => path.startsWith("daemon/"))) {
+                const lifecycleManifest = { package: info.package, capabilities: { rootOps: true, ...(background ? { jobs: { worker: "sha256-v1" } } : {}) } };
+                for (const hook of ["preuninst", "preupgrade", "start-stop-status"]) {
+                    if (readOptional(join(dir, "scripts", hook)) !== renderStandaloneScript(hook, lifecycleManifest))
+                        findings.push(`Executor scripts/${hook} differs from fixed lifecycle.`);
+                }
+            }
+            for (const [name, text] of Object.entries(renderUninstallWizardFiles(info.package, "native", { executor: true }))) {
+                if (readOptional(join(dir, "WIZARD_UIFILES", name)) !== text)
+                    findings.push(`Executor WIZARD_UIFILES/${name} is missing cleanup guidance.`);
+            }
         }
         const cgiEntry = payload.find((entry) => entry.path === CGI_PAYLOAD_PATH);
-        if (kind === "native-go" && !cgiEntry) {
+        if (standalone && !cgiEntry) {
             findings.push(`payload 沒有 ${CGI_PAYLOAD_PATH}`);
         }
         else if (cgiEntry && cgiEntry.mode !== "0755") {
@@ -86,14 +94,16 @@ export async function inspectSpk(spkPath, expectedKind) {
         }
         return {
             kind,
+            ...(executor ? { executor } : {}),
+            ...(standalone ? { uninstallCleanup: uninstallCleanup(info.package, hasExecutor) } : {}),
             package: info.package,
             version: info.version,
             arch: info.arch,
             signed: existsSync(join(dir, "syno_signature.asc")),
             cgi: cgiEntry?.mode === "0755" ? CGI_PAYLOAD_PATH : undefined,
             payload,
-            ...(integration ? { integration } : {}),
             findings,
+            capabilities: (metadata.capabilities ?? []).map(name => ({ name, requiresAdminApproval: name === "rootOps" || name === "delegate" })),
         };
     }
     finally {
@@ -119,7 +129,7 @@ async function checkArch(dir, info, kind, hasCgi, findings) {
     if (families.size > 1) {
         findings.push(`INFO arch 混用多個架構（${[...families].join("、")}）；一個 SPK 只含一種架構的 binary`);
     }
-    if (kind !== "native-go" || !hasCgi || families.size !== 1)
+    if (kind === "container" || !hasCgi || families.size !== 1)
         return;
     const [declared] = families;
     const cgi = join(dir, "cgi-inspection");
@@ -133,7 +143,7 @@ async function checkArch(dir, info, kind, hasCgi, findings) {
         findings.push(`INFO arch 宣告 ${declared}，但 ${CGI_PAYLOAD_PATH} 是 ${actual} 的執行檔`);
     }
 }
-async function checkDaemon(dir, info, paths, payload, findings) {
+async function checkDaemon(dir, info, paths, payload, findings, executor) {
     if (![...paths].some(path => path.startsWith("daemon/")))
         return;
     if (info.precheckstartstop !== "yes")
@@ -154,7 +164,7 @@ async function checkDaemon(dir, info, paths, payload, findings) {
             throw new Error("invalid config");
         if (payload.find(p => p.path === `daemon/payload/${daemon.exec}`)?.mode !== "0755")
             throw new Error("missing executable");
-        const manifest = { package: info.package, daemon, ...(paths.has("integration/helper") ? { integration: {}, privilege: "root" } : {}) };
+        const manifest = { package: info.package, daemon, capabilities: executor ? { rootOps: true } : {} };
         if (readFileSync(join(unpacked, "daemon/config.json"), "utf8") !== daemonConfig(manifest))
             throw new Error("non-canonical daemon config");
         for (const hook of ["start-stop-status", "preupgrade", "preuninst"]) {
@@ -166,7 +176,7 @@ async function checkDaemon(dir, info, paths, payload, findings) {
         findings.push("daemon/config.json 或 payload 不符合固定 daemon 契約");
     }
 }
-function readInfo(path, findings, kind, identityPayload) {
+function readInfo(path, findings, kind) {
     if (!existsSync(path)) {
         findings.push("缺少 INFO");
         return {};
@@ -183,13 +193,10 @@ function readInfo(path, findings, kind, identityPayload) {
             findings.push(`INFO 缺少 ${key}`);
         }
     }
-    if (kind === "native-go" && (info.thirdparty !== "yes" || info.dsmuidir !== "ui")) {
+    if (kind !== "container" && (info.thirdparty !== "yes" || info.dsmuidir !== "ui")) {
         findings.push('INFO 必須有 thirdparty="yes" 與 dsmuidir="ui"，DSM 才會提供 /webman/3rdparty/<package>/');
     }
-    const allowedDependency = kind === "container"
-        ? info.install_dep_packages?.split(":").every(dep => /^(WebStation|ContainerManager)([><=].*)?$/.test(dep))
-        : kind === "native-go" && identityPayload && info.install_dep_packages === "Node.js_v22";
-    if (info.install_dep_packages && !allowedDependency) {
+    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}`);
     }
     return info;
@@ -216,7 +223,7 @@ function readOptional(path) {
 function checkConf(dir, findings, kind, background, sharedFolder, pkg) {
     const confDir = join(dir, "conf");
     const entries = existsSync(confDir) ? readdirSync(confDir) : [];
-    const nativeResource = kind === "native-go" ? renderStandaloneResource({ package: pkg ?? "", ...(background ? { background: { worker: "sha256-v1" } } : {}), ...(sharedFolder ? { sharedFolder } : {}) }) : undefined;
+    const nativeResource = kind !== "container" ? renderStandaloneResource({ package: pkg ?? "", capabilities: background ? { jobs: { worker: "sha256-v1" } } : {}, ...(sharedFolder ? { sharedFolder } : {}) }) : undefined;
     if (nativeResource !== undefined && readOptional(join(confDir, "resource")) !== nativeResource) {
         findings.push(`conf/resource 必須是 ${nativeResource}（只有官方 data-share 與 systemd-user-unit，且與 install.sharedFolder 宣告一致）`);
     }
@@ -262,7 +269,7 @@ function checkConf(dir, findings, kind, background, sharedFolder, pkg) {
     }
 }
 /** The opt-in package user unit must be exactly what the generator writes. */
-function checkBackground(dir, info, payload, findings) {
+function checkBackground(dir, info, payload, findings, executor) {
     const pkg = info.package;
     if (!pkg)
         return;
@@ -274,7 +281,7 @@ function checkBackground(dir, info, payload, findings) {
     if (units.length !== 1 || units[0] !== unit || read(`${BACKGROUND_UNIT_DIR}/${unit}`) !== renderBackgroundUnit(pkg)) {
         findings.push(`${BACKGROUND_UNIT_DIR} 必須只有固定的 ${unit}（套件帳號執行，無 User=、無 root）`);
     }
-    if (read("scripts/start-stop-status") !== renderBackgroundControl(pkg))
+    if (read("scripts/start-stop-status") !== renderStandaloneScript("start-stop-status", { package: pkg, capabilities: { jobs: { worker: "sha256-v1" }, ...(executor ? { rootOps: true } : {}) } }))
         findings.push("background scripts/start-stop-status 與固定 synosystemctl lifecycle 不符");
 }
 /**
@@ -355,9 +362,9 @@ function checkUninstall(dir, findings) {
         if (!UPGRADE_GUARD.test(body))
             findings.push('UNINSTALL_NO_UPGRADE_GUARD scripts/postuninst 刪除資料但沒有 [ "$SYNOPKG_PKG_STATUS" != UPGRADE ] 防護，升級時會誤刪');
         if (!/is_package_area\(\)\s*\{/.test(body) || !/if ! is_package_area "\$real"/.test(body))
-            findings.push("UNINSTALL_UNSAFE_DELETE scripts/postuninst 刪除的路徑沒有驗證落在 /volumeN/@appdata|@apphome|@appstore/<package>；變數為空或指向別處時會刪錯資料");
+            findings.push("UNINSTALL_UNSAFE_DELETE scripts/postuninst 刪除的路徑沒有驗證落在 /volumeN/@appdata|@apphome|@appconf|@appstore/<package>；變數為空或指向別處時會刪錯資料");
         for (const line of body.split("\n").filter(l => DELETE_COMMAND.test(l))) {
-            for (const path of line.match(/\/volume\w*\/(?!@app(data|home|store)\/)[^\s"'$;]*/g) ?? [])
+            for (const path of line.match(/\/volume\w*\/(?!@app(data|home|conf|store)\/)[^\s"'$;]*/g) ?? [])
                 findings.push(`UNINSTALL_UNSAFE_DELETE scripts/postuninst 刪除 ${path}，不在套件自己的 @app* 目錄內`);
         }
         if (!boxes.some(box => box.name === "uninstall_uifile"))

package/dist/standalone/lifecycle.d.ts

@@ -1,3 +1,3 @@
 import type { StandaloneManifest } from "./manifest.js";
-/** Non-privileged hooks: precheck gates DSM management; no hook tears down root. */
+/** Package-account lifecycle hooks for CGI, daemon and background packages. */
 export declare function renderStandaloneScript(name: string, manifest: StandaloneManifest): string;

package/dist/standalone/lifecycle.js

@@ -1,35 +1,35 @@
-import { hasHelper } from "./helper-inventory.js";
-import { renderHelperStoppedCheck } from "./lifecycle-helper.js";
-import { renderBackgroundControl } from "./background.js";
+import { renderBackgroundControl, backgroundUnitName } from "./background.js";
 import { renderPackagePostuninst } from "../build-spk/native-lifecycle.js";
 import { renderSharedFolderScript } from "./shared-folder.js";
-/** Non-privileged hooks: precheck gates DSM management; no hook tears down root. */
+/** Package-account lifecycle hooks for CGI, daemon and background packages. */
 export function renderStandaloneScript(name, manifest) {
+    if ((manifest.capabilities?.rootOps || manifest.capabilities?.delegate) && ["preuninst", "preupgrade", "start-stop-status"].includes(name)) {
+        const helper = `"\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}/executor/lifecycle"`;
+        const stopWorker = manifest.capabilities.jobs ? `/usr/syno/bin/synosystemctl stop ${backgroundUnitName(manifest.package)} || echo "worker stop unconfirmed; continuing executor cleanup" >&2\n` : "";
+        const request = (action) => `${helper} ${action} --package ${manifest.package} || exit $?\n`;
+        if (name === "start-stop-status") {
+            const normal = renderStandaloneScript(name, { ...manifest, capabilities: { ...manifest.capabilities, rootOps: undefined, delegate: undefined } });
+            // Attempt worker stop first. DSM may have already stopped it or deny this
+            // lifecycle context; executor shutdown drains requests and closes ingress.
+            const stopDaemon = manifest.daemon ? `"/var/packages/${manifest.package}/target/daemon/control" stop "\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}" "\${SYNOPKG_PKGVAR:-/var/packages/${manifest.package}/var}" || exit $?\n` : "";
+            return normal.replace("#!/bin/sh\n", `#!/bin/sh\nif [ "$1" = start ]; then\n${request("start")}fi\nif [ "$1" = stop ]; then\n${stopWorker}${stopDaemon}${request("stop")}exit 0\nfi\n`);
+        }
+        const action = name === "preuninst" ? '"$action"' : "stop";
+        const choose = name === "preuninst" ? 'action=purge\n[ "${SYNOPKG_PKG_STATUS:-}" != UPGRADE ] || action=stop\n' : "";
+        return `#!/bin/sh\n${stopWorker}${choose}${request(action)}${manifest.daemon ? renderDaemonScript(name, manifest).replace("#!/bin/sh\n", "") : "exit 0\n"}`;
+    }
     if (name === "postuninst")
         return renderPackagePostuninst(manifest.package);
+    if ((manifest.capabilities?.rootOps || manifest.capabilities?.delegate) && ["postinst", "postupgrade"].includes(name)) {
+        const normal = renderStandaloneScript(name, { ...manifest, capabilities: { ...manifest.capabilities, rootOps: undefined, delegate: undefined } });
+        return normal.replace("#!/bin/sh\n", `#!/bin/sh\n"\${SYNOPKG_PKGDEST:-/var/packages/${manifest.package}/target}/executor/lifecycle" start --package ${manifest.package} || exit $?\n`);
+    }
     if (manifest.sharedFolder && (name === "postinst" || name === "postupgrade"))
         return renderSharedFolderScript(manifest.package, manifest.sharedFolder);
     if (manifest.daemon)
         return renderDaemonScript(name, manifest);
-    if (manifest.background && name === "start-stop-status")
+    if (manifest.capabilities.jobs && name === "start-stop-status")
         return renderBackgroundControl(manifest.package);
-    if (hasHelper(manifest) && ["preupgrade", "preuninst", "start-stop-status"].includes(name)) {
-        const check = renderHelperStoppedCheck(manifest.package);
-        if (name !== "start-stop-status")
-            return `#!/bin/sh\n${check}`;
-        return `#!/bin/sh
-case "$1" in
-  # Start the ordinary app even when integration is disabled or needs cleanup.
-  # No root enable/recover here; the administrator must explicitly approve it.
-  prestart|start|status) exit 0 ;;
-  prestop|stop)
-  # prestop is the management veto. stop runs inside ExecStop: its failure
-  # reports unsafe residue but cannot keep the DSM unit active.
-${check}    ;;
-  *) exit 1 ;;
-esac
-`;
-    }
     if (name === "start-stop-status") {
         return `#!/bin/sh
 case "$1" in
@@ -44,19 +44,23 @@ function renderDaemonScript(name, manifest) {
     const pkg = manifest.package;
     const control = `"/var/packages/${pkg}/target/daemon/control"`;
     const paths = `"\${SYNOPKG_PKGDEST:-/var/packages/${pkg}/target}" "\${SYNOPKG_PKGVAR:-/var/packages/${pkg}/var}"`;
-    const check = hasHelper(manifest) ? renderHelperStoppedCheck(pkg) : "";
-    if (["preupgrade", "preuninst"].includes(name))
-        return `#!/bin/sh\n${check}exec ${control} ${name === "preuninst" && manifest.daemon?.uninstall_args ? "uninstall" : "stop"} ${paths}\n`;
+    // Preserve the existing Connect upgrade safeguard when moving to this SDK:
+    // DSM also runs the outgoing preuninst hook during package upgrades.
+    if (["preupgrade", "preuninst"].includes(name)) {
+        const uninstall = name === "preuninst" && manifest.daemon?.uninstall_args;
+        const upgrade = uninstall ? `if [ "\${SYNOPKG_PKG_STATUS:-}" = "UPGRADE" ]; then\n  exec ${control} stop ${paths}\nfi\n` : "";
+        return `#!/bin/sh\n${upgrade}exec ${control} ${uninstall ? "uninstall" : "stop"} ${paths}\n`;
+    }
     if (name !== "start-stop-status")
         return "#!/bin/sh\nexit 0\n";
     return `#!/bin/sh
 case "$1" in
   prestart) exit 0 ;;
   prestop)
-${check}    exit 0 ;;
+    exit 0 ;;
   start|status) exec ${control} "$1" ${paths} ;;
   stop|restart)
-${check}    exec ${control} "$1" ${paths} ;;
+    exec ${control} "$1" ${paths} ;;
   *) exit 1 ;;
 esac
 `;

package/dist/standalone/manifest.d.ts

@@ -1,10 +1,12 @@
+import { type DelegateCapability } from "../runtime/executor-policy.js";
+import type { ExecutorPins } from "../runtime/executor-tasks.js";
 import { type NativeArchFamily } from "../build-spk/dsm-arch.js";
 import { type Catalogs, type Locale } from "./i18n.js";
 import { type RootOp } from "./root-ops.js";
-import { type Integration } from "./helper.js";
 import { type Daemon } from "./daemon.js";
 import { type Background } from "./background.js";
 import { type SharedFolder } from "./shared-folder.js";
+import { type ApiPermissions } from "./api-permissions.js";
 /**
  * `dsm-package.yaml`: a Standalone Package, i.e. an unsigned native SPK that
  * runs as its own DSM package account with a CGI backend and a DSM window UI.
@@ -41,6 +43,10 @@ export interface StandaloneManifest {
     os_min_ver: string;
     arches: NativeArchFamily[];
     backend: StandaloneBackend;
+    /** Effective App and SDK route policies used by the launcher and CGI. */
+    apiPermissions?: ApiPermissions;
+    apiPermissionsDigest?: string;
+    apiSDKPermissionsDigest?: string;
     ui: {
         dir: string;
         build?: {
@@ -49,24 +55,21 @@ export interface StandaloneManifest {
         };
     };
     i18n?: StandaloneI18n;
-    /**
-     * `none`: the package account only; an integration then has no helper.
-     * `root`: adds DSM-approved root tasks and, with an integration, its helper.
-     */
-    privilege: "none" | "root";
-    /** `root/<name>.sh`, present exactly when privilege is root (empty for a helper-only integration). */
+    capabilities: Capabilities;
+    /** Fixed root/<name>.sh operations, enabled by capabilities.rootOps. */
     rootOps?: RootOp[];
-    integration?: Integration;
+    executor?: ExecutorPins;
     daemon?: Daemon;
-    background?: Background;
-    /**
-     * `session`: the package account serves the interactive File Station routes
-     * through each caller's own DSM session. No helper, no stored credential.
-     */
-    fileStation?: "session";
     /** `install.sharedFolder`: the Shared Folder the install wizard selects or `data-share` creates. */
     sharedFolder?: SharedFolder;
 }
+export interface Capabilities {
+    files?: "session";
+    identity?: "standalone";
+    jobs?: Background;
+    rootOps?: true;
+    delegate?: DelegateCapability;
+}
 export interface StandaloneError {
     code: string;
     message: string;

package/dist/standalone/manifest.js

@@ -1,15 +1,15 @@
+import { validDelegate } from "../runtime/executor-policy.js";
 import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { parse } from "yaml";
 import { isNativeArchFamily } from "../build-spk/dsm-arch.js";
 import { checkGlossary, isLocale, loadCatalogs } from "./i18n.js";
 import { loadRootOps, ROOT_OPS_DIR } from "./root-ops.js";
-import { readIntegration } from "./helper.js";
-import { hasHelper } from "./helper-inventory.js";
 import { readDaemon } from "./daemon.js";
 import { readBackground } from "./background.js";
 import { DEFAULT_MIN_DSM, isDsmAtLeast } from "../build-spk/dsm-version.js";
 import { readSharedFolder } from "./shared-folder.js";
+import { readApiPermissions } from "./api-permissions.js";
 /**
  * `dsm-package.yaml`: a Standalone Package, i.e. an unsigned native SPK that
  * runs as its own DSM package account with a CGI backend and a DSM window UI.
@@ -17,7 +17,7 @@ import { readSharedFolder } from "./shared-folder.js";
 export const STANDALONE_MANIFEST = "dsm-package.yaml";
 const KNOWN_FIELDS = new Set([
     "schema", "package", "version", "build", "displayname", "description",
-    "maintainer", "os_min_ver", "arches", "backend", "ui", "privilege", "i18n", "integration", "daemon", "background", "fileStation", "install",
+    "maintainer", "os_min_ver", "arches", "backend", "ui", "capabilities", "i18n", "daemon", "install",
 ]);
 const I18N_FIELDS = new Set(["messages", "glossary", "info"]);
 const INFO_TEXT_FIELDS = new Set(["displayname", "description"]);
@@ -70,6 +70,8 @@ export function loadStandaloneManifest(root) {
         return { ok: false, errors: [{ code: "STANDALONE_MANIFEST_YAML", message: String(error) }] };
     }
     const c = new Collector(root);
+    if (existsSync(join(root, "compose.yaml")))
+        c.fail("PROJECT_RUNTIME_EXCLUSIVE", "compose.yaml 與 dsm-package.yaml 互斥；請保留其中一個。");
     if (!isRecord(raw)) {
         c.fail("STANDALONE_MANIFEST_YAML", `${STANDALONE_MANIFEST} 必須是 YAML 物件。`);
         return { ok: false, errors: c.errors };
@@ -83,14 +85,11 @@ function readManifest(raw, c) {
             c.fail("STANDALONE_FIELD_UNKNOWN", `不支援的欄位「${key}」。Standalone Package 不接受自訂 lifecycle scripts 或 DSM conf。`);
         }
     }
-    if (raw.schema !== 1) {
-        c.fail("STANDALONE_SCHEMA_INVALID", "schema 必須是 1。");
+    if (raw.schema !== 2) {
+        c.fail("STANDALONE_SCHEMA_INVALID", "schema: 2 必填；請改成 schema: 2、backend.kind: go|binary，並將 privilege: root、background、fileStation 分別改為 capabilities.rootOps: true、capabilities.jobs: true、capabilities.files: session。");
     }
-    const privilege = raw.privilege === "none" || raw.privilege === "root"
-        ? raw.privilege
-        : c.fail("STANDALONE_PRIVILEGE_UNSUPPORTED", "privilege 只接受 none（只用套件帳號）或 root（由 DSM 管理員核准的 root 工作）；請見 README「Root access」。");
-    const integration = readIntegration(raw.integration, c.root, e => c.fail(e.code, e.message));
-    const rootOps = privilege && readRootOps(privilege, integration !== undefined, c);
+    const capabilities = readCapabilities(raw.capabilities, c);
+    const rootOps = readRootOps(capabilities.rootOps === true, c);
     const packageId = typeof raw.package === "string" && PACKAGE_ID.test(raw.package)
         ? raw.package
         : c.fail("STANDALONE_PACKAGE_INVALID", "package 必須以英文字母開頭，只含英數字（2–64 字）。");
@@ -103,7 +102,7 @@ function readManifest(raw, c) {
     const osMinVer = typeof raw.os_min_ver === "string" && OS_MIN_VER.test(raw.os_min_ver)
         ? raw.os_min_ver
         : c.fail("STANDALONE_OS_MIN_VER_INVALID", "os_min_ver 格式為 <major>.<minor>-<build>，例如 7.2-64570。");
-    if (privilege === "root" && osMinVer && !isDsmAtLeast(osMinVer, DEFAULT_MIN_DSM)) {
+    if (capabilities.rootOps === true && osMinVer && !isDsmAtLeast(osMinVer, DEFAULT_MIN_DSM)) {
         c.fail("STANDALONE_OS_MIN_VER_INVALID", `root templates require DSM ${DEFAULT_MIN_DSM} or later.`);
     }
     const displayname = c.text(raw.displayname, "displayname");
@@ -111,20 +110,32 @@ function readManifest(raw, c) {
     const maintainer = c.text(raw.maintainer, "maintainer");
     const arches = readArches(raw.arches, c);
     const backend = arches && readBackend(raw.backend, arches, c);
+    let permissions;
+    if (backend?.kind === "go") {
+        try {
+            permissions = readApiPermissions(backend.dir, capabilities);
+        }
+        catch (error) {
+            c.fail("STANDALONE_API_PERMISSIONS_INVALID", `backend/internal/api/permissions.json must define the centralized API policy: ${String(error)}`);
+        }
+    }
     const daemon = arches && readDaemon(raw.daemon, c.root, arches, e => c.fail(e.code, e.message));
-    if (integration && (backend?.kind !== "go" || rootOps?.some(op => op.name.startsWith("helper_")) || (privilege === "none" && !isPackageOnly(integration)))) {
-        c.fail("STANDALONE_INTEGRATION_INVALID", "integration 需要 backend.go；helper_ 操作名稱保留給 generator。privilege: none 只提供套件帳號整合（protocol 1、workers 為空，可選 identity），helper 設定需要 privilege: root。");
+    if (capabilities.jobs && raw.daemon !== undefined) {
+        c.fail("CAPABILITY_COMBINATION_INVALID", "daemon 與 capabilities.jobs 互斥。");
     }
-    const background = readBackground(raw.background, e => c.fail(e.code, e.message));
-    if (raw.background !== undefined && (backend?.kind !== "go" || raw.daemon !== undefined || privilege === "root")) {
-        c.fail("STANDALONE_BACKGROUND_INVALID", "background 需要 backend.go（worker 由專案的 Go module 編譯）與 privilege: none，且不能與 daemon 並用；套件帳號 integration 可並用，root helper 不行。");
+    if (backend?.kind === "binary") {
+        for (const name of ["files", "jobs", "identity", "delegate"]) {
+            if (isRecord(raw.capabilities) && raw.capabilities[name] !== undefined)
+                c.fail("CAPABILITY_UNSUPPORTED", `backend.kind: binary 不支援 capabilities.${name}。`);
+        }
     }
-    const fileStation = raw.fileStation === undefined ? undefined : readFileStation(raw.fileStation, backend?.kind === "go" && !hasHelper({ integration, privilege }), c);
     const sharedFolder = raw.install === undefined ? undefined : readSharedFolder(raw.install, e => c.fail(e.code, e.message));
     const ui = readUi(raw.ui, c);
+    if (capabilities.identity && ui && !ui.build)
+        c.fail("CAPABILITY_COMBINATION_INVALID", "capabilities.identity 需要獨立登入頁；plain UI 不支援，請改用 vue UI（init --ui vue）。");
     const i18n = raw.i18n === undefined ? undefined : readI18n(raw.i18n, c);
     if (!packageId || !version || !build || !osMinVer || !displayname || !description || !maintainer
-        || !arches || !backend || !ui || !privilege || (privilege === "root" && !rootOps)) {
+        || !arches || !backend || !ui || (capabilities.rootOps === true && !rootOps)) {
         return undefined;
     }
     return {
@@ -139,33 +150,22 @@ function readManifest(raw, c) {
         os_min_ver: osMinVer,
         arches,
         backend,
+        ...(permissions ? { apiPermissions: permissions.policy, apiPermissionsDigest: permissions.digest, apiSDKPermissionsDigest: permissions.sdkDigest } : {}),
         ui,
         ...(i18n ? { i18n } : {}),
-        privilege,
+        capabilities,
         ...(rootOps ? { rootOps } : {}),
-        ...(integration ? { integration } : {}),
         ...(daemon ? { daemon } : {}),
-        ...(background ? { background } : {}),
-        ...(fileStation ? { fileStation } : {}),
         ...(sharedFolder ? { sharedFolder } : {}),
     };
 }
-/** Without privilege: root there is no helper, so none of its inventory settings apply. */
-function isPackageOnly(integration) {
-    return integration.protocol === 1 && Object.keys(integration.workers).length === 0
-        && integration.dataAccess === undefined && integration.sdkWorkers === undefined;
-}
-/** A root integration's helper tasks are generated; it needs no root/ operation of its own. */
-function readRootOps(privilege, hasIntegration, c) {
+function readRootOps(enabled, c) {
     const dir = join(c.root, ROOT_OPS_DIR);
-    if (privilege === "none") {
+    if (!enabled) {
         return existsSync(dir)
-            ? c.fail("STANDALONE_ROOT_OPS_UNUSED", `${ROOT_OPS_DIR}/ 只用在 privilege: root；privilege: none 的套件不會執行它。`)
+            ? c.fail("STANDALONE_ROOT_OPS_UNUSED", `${ROOT_OPS_DIR}/ 需要 capabilities.rootOps: true；請宣告能力或刪除此目錄。`)
             : undefined;
     }
-    if (hasIntegration && !existsSync(dir)) {
-        return [];
-    }
     const loaded = loadRootOps(dir);
     if (!loaded.ok) {
         loaded.errors.forEach((e) => c.fail(e.code, e.message));
@@ -183,32 +183,31 @@ function readArches(value, c) {
         : c.fail("STANDALONE_ARCHES_INVALID", "arches 必須是不重複的 x86_64／aarch64 清單，至少一個。");
 }
 function readBackend(value, arches, c) {
-    if (!isRecord(value) || ("go" in value) === ("binary" in value)) {
-        return c.fail("STANDALONE_BACKEND_INVALID", "backend 必須恰好有 go 或 binary 其中之一。");
+    if (!isRecord(value) || !["go", "binary"].includes(String(value.kind))) {
+        return c.fail("STANDALONE_BACKEND_INVALID", "backend.kind 必須是 go 或 binary。");
     }
-    if ("go" in value) {
-        const go = value.go;
-        if (!isRecord(go) || typeof go.main !== "string" || !GO_MAIN.test(go.main) || go.main.includes("..")) {
-            return c.fail("STANDALONE_BACKEND_INVALID", "backend.go 需要 dir 與以 ./ 開頭的 main（例如 ./cmd/app）。");
+    if (value.kind === "go") {
+        if (Object.keys(value).some(key => !["kind", "dir", "main"].includes(key)) || (value.main !== undefined && (typeof value.main !== "string" || !GO_MAIN.test(value.main) || value.main.includes("..")))) {
+            return c.fail("STANDALONE_BACKEND_INVALID", "backend.kind: go 需要 dir，可選 main（預設 ./cmd/app）。");
         }
-        const dir = c.path(go.dir, "backend.go.dir");
-        return dir ? { kind: "go", dir, main: go.main } : undefined;
+        const dir = c.path(value.dir, "backend.dir");
+        return dir ? { kind: "go", dir, main: value.main ?? "./cmd/app" } : undefined;
     }
-    const binary = value.binary;
-    if (!isRecord(binary)) {
-        return c.fail("STANDALONE_BACKEND_INVALID", "backend.binary 必須以架構為 key 指向 CGI 執行檔。");
+    const binary = value.files;
+    if (!isRecord(binary) || Object.keys(value).some(key => !["kind", "files"].includes(key))) {
+        return c.fail("STANDALONE_BACKEND_INVALID", "backend.kind: binary 需要 files，以架構為 key 指向 CGI 執行檔。");
     }
     const files = {};
     for (const arch of arches) {
         if (!(arch in binary)) {
-            c.fail("STANDALONE_BINARY_ARCH_MISSING", `arches 宣告了 ${arch}，但 backend.binary 沒有它的執行檔。`);
+            c.fail("STANDALONE_BINARY_ARCH_MISSING", `arches 宣告了 ${arch}，但 backend.files 沒有它的執行檔。`);
             continue;
         }
-        files[arch] = c.path(binary[arch], `backend.binary.${arch}`);
+        files[arch] = c.path(binary[arch], `backend.files.${arch}`);
     }
     for (const key of Object.keys(binary)) {
         if (!arches.includes(key)) {
-            c.fail("STANDALONE_BACKEND_INVALID", `backend.binary.${key} 不在 arches 內。`);
+            c.fail("STANDALONE_BACKEND_INVALID", `backend.files.${key} 不在 arches 內。`);
         }
     }
     return Object.values(files).every(Boolean) ? { kind: "binary", files } : undefined;
@@ -302,9 +301,34 @@ export function findStandaloneRoot(start) {
         current = parent;
     }
 }
-function readFileStation(value, allowed, c) {
-    if (value === "session" && allowed)
-        return "session";
-    c.fail("STANDALONE_FILESTATION_INVALID", "fileStation 只接受 session，需要 backend.go，且不能與 root helper integration 並用（helper 有自己的 File Station gate）。");
-    return undefined;
+function readCapabilities(value, c) {
+    if (value === undefined)
+        return {};
+    if (!isRecord(value)) {
+        c.fail("CAPABILITY_INVALID", "capabilities 必須是物件。");
+        return {};
+    }
+    const result = {};
+    for (const [name, setting] of Object.entries(value)) {
+        if (name === "delegate") {
+            if (validDelegate(setting))
+                result.delegate = setting;
+            else
+                c.fail("CAPABILITY_INVALID", "delegate requires nonempty unique §2.4 files operations and scope home or shared:<name>.");
+        }
+        else if (name === "files" && setting === "session")
+            result.files = "session";
+        else if (name === "identity" && setting === "standalone")
+            result.identity = "standalone";
+        else if (name === "rootOps" && setting === true)
+            result.rootOps = true;
+        else if (name === "jobs") {
+            result.jobs = readBackground(setting === true ? { worker: "sha256-v1" } : setting, e => c.fail("CAPABILITY_INVALID", e.message.replace("background", "capabilities.jobs")));
+        }
+        else
+            c.fail("CAPABILITY_INVALID", `不支援的 capabilities.${name} 值；files: session、identity: standalone、jobs: true 或 {worker: sha256-v1}、rootOps: true。`);
+    }
+    if (result.delegate && !result.jobs)
+        result.jobs = { worker: "sha256-v1" };
+    return result;
 }