@synopackageland/cli 0.1.0 → 0.2.0

package/dist/build-spk/broker-glue.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The Broker installer glue every Managed Profile App carries, independent of
+ * runtime. Compose and native Apps install through the same socket, so the
+ * Local Attestation gate and the registration-status probe live here once.
+ */
+/** Shell variable preamble locating the Broker installer and its socket. */
+export declare const BROKER_INSTALLER_VARS = "INSTALLER=\"${BROKER_INSTALLER:-/var/packages/SynoPkgLandService/target/bin/synopkgland-installer}\"\nSOCKET=\"${BROKER_SOCKET:-/var/packages/SynoPkgLandService/var/installer.sock}\"";
+/**
+ * The `status` probe: asks the Broker whether this App is still registered.
+ * `removed` exits 150 so DSM shows the App as removed by the platform;
+ * `unknown` exits 4. Anything else falls through to the caller, which decides
+ * what "running" means for its runtime.
+ */
+export declare function renderBrokerStatusProbe(packageIdentity: string): string;
+/** `preinst` / `preupgrade`: refuse to install when the Broker socket is absent. */
+export declare const BROKER_SOCKET_REQUIRED_SCRIPT = "#!/bin/sh\nSOCKET=\"${BROKER_SOCKET:-/var/packages/SynoPkgLandService/var/installer.sock}\"\nif [ ! -S \"$SOCKET\" ]; then\n  echo \"SynoPkgLandService installer socket is not available\" >&2\n  exit 1\nfi\nexit 0\n";

package/dist/build-spk/broker-glue.js

@@ -0,0 +1,40 @@
+/**
+ * The Broker installer glue every Managed Profile App carries, independent of
+ * runtime. Compose and native Apps install through the same socket, so the
+ * Local Attestation gate and the registration-status probe live here once.
+ */
+/** Shell variable preamble locating the Broker installer and its socket. */
+export const BROKER_INSTALLER_VARS = `INSTALLER="\${BROKER_INSTALLER:-/var/packages/SynoPkgLandService/target/bin/synopkgland-installer}"
+SOCKET="\${BROKER_SOCKET:-/var/packages/SynoPkgLandService/var/installer.sock}"`;
+/**
+ * The `status` probe: asks the Broker whether this App is still registered.
+ * `removed` exits 150 so DSM shows the App as removed by the platform;
+ * `unknown` exits 4. Anything else falls through to the caller, which decides
+ * what "running" means for its runtime.
+ */
+export function renderBrokerStatusProbe(packageIdentity) {
+    return `    if [ -x "$INSTALLER" ] && [ -S "$SOCKET" ]; then
+      "$INSTALLER" --socket "$SOCKET" --phase status --attempt-id "status-$$" \\
+        --package-identity "${packageIdentity}" --package-version "\${SYNOPKG_PKGVER}" \\
+        --package-path "\${SYNOPKG_PKGDEST}" --bundle-path "\${SYNOPKG_PKGDEST}" \\
+        --pkg-var "\${SYNOPKG_PKGVAR}" --pkg-home "\${SYNOPKG_PKGHOME}" >/tmp/synopkgland-status.$$ 2>/dev/null || true
+      if grep -q '"registrationStatus":"removed"' /tmp/synopkgland-status.$$ 2>/dev/null; then
+        rm -f /tmp/synopkgland-status.$$
+        exit 150
+      fi
+      if grep -q '"registrationStatus":"unknown"' /tmp/synopkgland-status.$$ 2>/dev/null; then
+        rm -f /tmp/synopkgland-status.$$
+        exit 4
+      fi
+      rm -f /tmp/synopkgland-status.$$
+    fi`;
+}
+/** `preinst` / `preupgrade`: refuse to install when the Broker socket is absent. */
+export const BROKER_SOCKET_REQUIRED_SCRIPT = `#!/bin/sh
+SOCKET="\${BROKER_SOCKET:-/var/packages/SynoPkgLandService/var/installer.sock}"
+if [ ! -S "$SOCKET" ]; then
+  echo "SynoPkgLandService installer socket is not available" >&2
+  exit 1
+fi
+exit 0
+`;

package/dist/build-spk/delete-app-data.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The Delete App Data block shared by the Compose and native postuninst scripts.
+ *
+ * The uninstall wizard sets `delete_app_data` (and DSM mirrors it as
+ * `wizard_delete_app_data`); unchecked is the default, so an absent variable
+ * must leave the data in place. `delete_root` refuses to follow a symlink out
+ * of `@appdata`/`@apphome`, empties the directory rather than removing the
+ * mount point DSM owns, and reports remnants instead of failing the script —
+ * a non-zero postuninst blocks uninstall.
+ */
+export declare function renderDeleteAppDataBlock(roots: readonly string[]): string;

package/dist/build-spk/delete-app-data.js

@@ -0,0 +1,56 @@
+/**
+ * The Delete App Data block shared by the Compose and native postuninst scripts.
+ *
+ * The uninstall wizard sets `delete_app_data` (and DSM mirrors it as
+ * `wizard_delete_app_data`); unchecked is the default, so an absent variable
+ * must leave the data in place. `delete_root` refuses to follow a symlink out
+ * of `@appdata`/`@apphome`, empties the directory rather than removing the
+ * mount point DSM owns, and reports remnants instead of failing the script —
+ * a non-zero postuninst blocks uninstall.
+ */
+export function renderDeleteAppDataBlock(roots) {
+    const calls = roots.map((name) => `  delete_root "$${name}"`).join("\n");
+    return `should_delete=0
+case "\${delete_app_data:-}" in
+  true|True|TRUE|yes|1) should_delete=1 ;;
+esac
+case "\${wizard_delete_app_data:-}" in
+  true|True|TRUE|yes|1) should_delete=1 ;;
+esac
+if [ "$should_delete" -eq 1 ]; then
+  delete_root() {
+    target="$1"
+    if [ ! -e "$target" ] && [ ! -L "$target" ]; then
+      return 0
+    fi
+    if [ -L "$target" ]; then
+      real=$(readlink -f "$target" 2>/dev/null || true)
+      case "$real" in
+        */@appdata/*|*/@apphome/*)
+          ;;
+        *)
+          echo "Delete App Data skipped symlink: $target" >&2
+          return 0
+          ;;
+      esac
+    else
+      real="$target"
+    fi
+    if [ ! -e "$real" ]; then
+      return 0
+    fi
+    chmod -R u+w "$real" 2>/dev/null || true
+    if [ -d "$real" ]; then
+      find "$real" -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
+      leftover=$(find "$real" -mindepth 1 -maxdepth 1 2>/dev/null | head -n 1 || true)
+      if [ -n "$leftover" ]; then
+        echo "Delete App Data remnant: $real" >&2
+      fi
+    else
+      rm -f "$real" || echo "Delete App Data remnant: $real" >&2
+    fi
+  }
+${calls}
+fi
+`;
+}

package/dist/build-spk/generator.js

@@ -11,6 +11,11 @@ import { validateProject } from "../validate.js";
 import { writeDsmWindowIcons, writePackageCenterIcons } from "./dsm-icons.js";
 import { infoArchValue } from "./dsm-arch.js";
 import { createReproducibleTar } from "./reproducible-archive.js";
+import { renderDeleteAppDataBlock } from "./delete-app-data.js";
+import { BROKER_INSTALLER_VARS, BROKER_SOCKET_REQUIRED_SCRIPT, renderBrokerStatusProbe, } from "./broker-glue.js";
+import { loadNative } from "../native/load.js";
+import { materializeNativePayload } from "./native-payload.js";
+import { renderNativePrivilege, renderNativeStartStopStatus, renderNativePostuninst, } from "./native-lifecycle.js";
 const FILE_MODE = 0o644;
 const SCRIPT_MODE = 0o755;
 const INSTALL_UIFILE = "install_uifile";
@@ -48,6 +53,82 @@ export async function buildSpk(options) {
     if (options.spkVersion) {
         contract.version = options.spkVersion;
     }
+    const nativePath = options.project.nativePath ?? join(options.project.root, "native.yaml");
+    const isNative = existsSync(nativePath);
+    if (isNative) {
+        if (!options.archFamily) {
+            return { ok: false, errors: ["NATIVE_ARCH_FAMILY_REQUIRED"] };
+        }
+        const parsedNative = loadNative(nativePath);
+        if (!parsedNative) {
+            return { ok: false, errors: ["NATIVE_LOAD_FAILED"] };
+        }
+        const targetSource = parsedNative.native.targets[options.archFamily];
+        if (!targetSource) {
+            return { ok: false, errors: ["NATIVE_TARGET_NOT_DECLARED"] };
+        }
+        const staging = mkdtempSync(join(tmpdir(), "syno-spk-"));
+        try {
+            writeFileSync(join(staging, "INFO"), renderInfo(contract, options.archFamily), "utf8");
+            writePackageCenterIcons(staging);
+            mkdirSync(join(staging, "conf"), { recursive: true });
+            writeFileSync(join(staging, "conf", "privilege"), renderNativePrivilege(), "utf8");
+            writeFileSync(join(staging, "privilege"), renderNativePrivilege(), "utf8");
+            mkdirSync(join(staging, "WIZARD_UIFILES"), { recursive: true });
+            writeFileSync(join(staging, "WIZARD_UIFILES", INSTALL_UIFILE), JSON.stringify(renderInstallWizard(contract, undefined), null, 2), "utf8");
+            writeFileSync(join(staging, "WIZARD_UIFILES", UPGRADE_UIFILE), JSON.stringify(renderUpgradeWizard(contract, undefined), null, 2), "utf8");
+            writeFileSync(join(staging, "WIZARD_UIFILES", UNINSTALL_UIFILE), JSON.stringify(renderUninstallWizard(), null, 2), "utf8");
+            mkdirSync(join(staging, "scripts"), { recursive: true });
+            for (const name of SCRIPT_NAMES) {
+                const scriptPath = join(staging, "scripts", name);
+                writeFileSync(scriptPath, renderManagedScript(name, contract, { config: parsedNative.native }), "utf8");
+                chmodSync(scriptPath, SCRIPT_MODE);
+            }
+            const packageDir = join(staging, "package");
+            mkdirSync(packageDir, { recursive: true });
+            // 1. Materialize native payload
+            try {
+                await materializeNativePayload({
+                    source: targetSource,
+                    projectRoot: options.project.root,
+                    destDir: packageDir,
+                });
+            }
+            catch (err) {
+                const code = err && typeof err === "object" && "code" in err
+                    ? String(err.code)
+                    : "NATIVE_PAYLOAD_ERROR";
+                return { ok: false, errors: [code] };
+            }
+            // Check collision with App Bundle members before copying
+            if (existsSync(join(packageDir, "synology-app.yaml")) ||
+                existsSync(join(packageDir, "native.yaml"))) {
+                return { ok: false, errors: ["NATIVE_PAYLOAD_BUNDLE_COLLISION"] };
+            }
+            copyFileSync(options.project.contractPath, join(packageDir, "synology-app.yaml"));
+            copyFileSync(nativePath, join(packageDir, "native.yaml"));
+            if (options.embeddedAttestationToken !== undefined) {
+                const attestationPath = join(packageDir, EMBEDDED_ATTESTATION_RELATIVE_PATH);
+                mkdirSync(join(packageDir, ".synopkgland"), { recursive: true });
+                writeFileSync(attestationPath, options.embeddedAttestationToken, "utf8");
+                chmodSync(attestationPath, FILE_MODE);
+            }
+            chmodSync(join(staging, "INFO"), FILE_MODE);
+            chmodSync(join(staging, "privilege"), FILE_MODE);
+            chmodSync(join(staging, "WIZARD_UIFILES", INSTALL_UIFILE), FILE_MODE);
+            chmodSync(join(staging, "WIZARD_UIFILES", UPGRADE_UIFILE), FILE_MODE);
+            chmodSync(join(staging, "WIZARD_UIFILES", UNINSTALL_UIFILE), FILE_MODE);
+            chmodSync(join(packageDir, "synology-app.yaml"), FILE_MODE);
+            chmodSync(join(packageDir, "native.yaml"), FILE_MODE);
+            const outputPath = options.outputPath ??
+                join(options.project.root, `${String(contract.package)}-${options.archFamily}.spk`);
+            await createDeterministicSpk(staging, outputPath);
+            return { ok: true, outputPath, errors: [] };
+        }
+        finally {
+            rmSync(staging, { recursive: true, force: true });
+        }
+    }
     const staging = mkdtempSync(join(tmpdir(), "syno-spk-"));
     try {
         writeFileSync(join(staging, "INFO"), renderInfo(contract, options.archFamily), "utf8");
@@ -430,30 +511,52 @@ function renderUninstallWizard() {
             ],
         }];
 }
-function renderManagedScript(name, contract) {
+function renderManagedScript(name, contract, nativeContext) {
+    if (nativeContext) {
+        const lifecycleInput = {
+            packageIdentity: String(contract.package),
+            config: nativeContext.config,
+        };
+        if (name === "start-stop-status") {
+            return renderNativeStartStopStatus(lifecycleInput);
+        }
+        if (name === "preinst" || name === "preupgrade") {
+            return BROKER_SOCKET_REQUIRED_SCRIPT;
+        }
+        if (name === "postinst" || name === "postupgrade") {
+            const installerScript = renderInstallerCallScript(contract, name === "postupgrade" ? "update" : "install");
+            // The service process needs its scratch directory before it can start,
+            // and the installer call is the script's exit status, so widen the
+            // existing mkdir rather than appending after it.
+            return installerScript.replace('mkdir -p "${SYNOPKG_PKGVAR}" "${SYNOPKG_PKGHOME}/secrets"', 'mkdir -p "${SYNOPKG_PKGVAR}" "${SYNOPKG_PKGVAR}/tmp" "${SYNOPKG_PKGHOME}/secrets"');
+        }
+        if (name === "preuninst") {
+            // Compose installer uninstall (with UPGRADE early exit) + stop native process
+            const installerScript = renderInstallerCallScript(contract, "uninstall").replace("set -eu\n", 'set -eu\nif [ "${SYNOPKG_PKG_STATUS:-}" = "UPGRADE" ]; then\n  exit 0\nfi\n');
+            // Stop the process BEFORE deregistering: `set -eu` aborts the script if
+            // the installer fails, so a stop appended after it would never run. The
+            // stop itself is best effort -- DSM already calls `start-stop-status
+            // stop` directly (N0), and a non-zero preuninst blocks uninstall.
+            const preuninstStopBlock = `CONTROL="/var/packages/\${SYNOPKG_PKGNAME:-${contract.package}}/scripts/start-stop-status"
+if [ -x "$CONTROL" ]; then
+  "$CONTROL" stop 2>/dev/null || true
+fi
+`;
+            return installerScript.replace('"$INSTALLER"', `${preuninstStopBlock}"$INSTALLER"`);
+        }
+        if (name === "postuninst") {
+            return renderNativePostuninst(lifecycleInput);
+        }
+        return `#!/bin/sh\nexit 0\n`;
+    }
     if (name === "start-stop-status") {
         return `#!/bin/sh
-INSTALLER="\${BROKER_INSTALLER:-/var/packages/SynoPkgLandService/target/bin/synopkgland-installer}"
-SOCKET="\${BROKER_SOCKET:-/var/packages/SynoPkgLandService/var/installer.sock}"
+${BROKER_INSTALLER_VARS}
 case "$1" in
   start) exit 0 ;;
   stop) exit 0 ;;
   status)
-    if [ -x "$INSTALLER" ] && [ -S "$SOCKET" ]; then
-      "$INSTALLER" --socket "$SOCKET" --phase status --attempt-id "status-$$" \\
-        --package-identity "${contract.package}" --package-version "\${SYNOPKG_PKGVER}" \\
-        --package-path "\${SYNOPKG_PKGDEST}" --bundle-path "\${SYNOPKG_PKGDEST}" \\
-        --pkg-var "\${SYNOPKG_PKGVAR}" --pkg-home "\${SYNOPKG_PKGHOME}" >/tmp/synopkgland-status.$$ 2>/dev/null || true
-      if grep -q '"registrationStatus":"removed"' /tmp/synopkgland-status.$$ 2>/dev/null; then
-        rm -f /tmp/synopkgland-status.$$
-        exit 150
-      fi
-      if grep -q '"registrationStatus":"unknown"' /tmp/synopkgland-status.$$ 2>/dev/null; then
-        rm -f /tmp/synopkgland-status.$$
-        exit 4
-      fi
-      rm -f /tmp/synopkgland-status.$$
-    fi
+${renderBrokerStatusProbe(String(contract.package))}
     exit 0
     ;;
   *) exit 1 ;;
@@ -461,14 +564,7 @@ esac
 `;
     }
     if (name === "preinst" || name === "preupgrade") {
-        return `#!/bin/sh
-SOCKET="\${BROKER_SOCKET:-/var/packages/SynoPkgLandService/var/installer.sock}"
-if [ ! -S "$SOCKET" ]; then
-  echo "SynoPkgLandService installer socket is not available" >&2
-  exit 1
-fi
-exit 0
-`;
+        return BROKER_SOCKET_REQUIRED_SCRIPT;
     }
     if (name === "postinst" || name === "postupgrade") {
         return renderInstallerCallScript(contract, name === "postupgrade" ? "update" : "install");
@@ -482,50 +578,7 @@ set -eu
 PKGVAR="\${SYNOPKG_PKGVAR}"
 PKGHOME="\${SYNOPKG_PKGHOME}"
 SECRETS="\${PKGHOME}/secrets"
-should_delete=0
-case "\${delete_app_data:-}" in
-  true|True|TRUE|yes|1) should_delete=1 ;;
-esac
-case "\${wizard_delete_app_data:-}" in
-  true|True|TRUE|yes|1) should_delete=1 ;;
-esac
-if [ "$should_delete" -eq 1 ]; then
-  delete_root() {
-    target="$1"
-    if [ ! -e "$target" ] && [ ! -L "$target" ]; then
-      return 0
-    fi
-    if [ -L "$target" ]; then
-      real=$(readlink -f "$target" 2>/dev/null || true)
-      case "$real" in
-        */@appdata/*|*/@apphome/*)
-          ;;
-        *)
-          echo "Delete App Data skipped symlink: $target" >&2
-          return 0
-          ;;
-      esac
-    else
-      real="$target"
-    fi
-    if [ ! -e "$real" ]; then
-      return 0
-    fi
-    chmod -R u+w "$real" 2>/dev/null || true
-    if [ -d "$real" ]; then
-      find "$real" -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
-      leftover=$(find "$real" -mindepth 1 -maxdepth 1 2>/dev/null | head -n 1 || true)
-      if [ -n "$leftover" ]; then
-        echo "Delete App Data remnant: $real" >&2
-      fi
-    else
-      rm -f "$real" || echo "Delete App Data remnant: $real" >&2
-    fi
-  }
-  delete_root "$PKGVAR"
-  delete_root "$SECRETS"
-fi
-exit 0
+${renderDeleteAppDataBlock(["PKGVAR", "SECRETS"])}exit 0
 `;
     }
     return `#!/bin/sh

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

@@ -0,0 +1,51 @@
+import type { NativeConfig } from "../native/types.js";
+export interface NativeLifecycleInput {
+    packageIdentity: string;
+    config: NativeConfig;
+}
+/**
+ * Renders `conf/privilege` content.
+ * For non-container native packages, DSM accepts `{"defaults":{"run-as":"package"}}`.
+ */
+export declare function renderNativePrivilege(): string;
+/**
+ * Renders `scripts/start-stop-status`.
+ *
+ * Requirements & hard facts from N0:
+ * - Start must be backgrounded via `nohup setsid ... &` because Package Center uses a oneshot unit.
+ * - PID is tracked in `$PKGVAR/<pkg>.pid`.
+ * - Status exit codes: 0 = running, 1 = PID file present but process dead, 3 = stopped / no PID file.
+ * - Fallbacks for `SYNOPKG_PKGDEST` and `SYNOPKG_PKGVAR` via `:-/var/packages/<pkg>/target` and `:-/var/packages/<pkg>/var`.
+ * - `exec` is relative to `SYNOPKG_PKGDEST` (no `target/` subfolder).
+ * - Safe quoting for `exec`, `args`, and `env`.
+ */
+export declare function renderNativeStartStopStatus(input: NativeLifecycleInput): string;
+/**
+ * Renders `scripts/postinst`.
+ *
+ * Requirements from N0:
+ * - DSM creates the package user/group and sets up `SYNOPKG_PKGVAR` (drwxr-xr-x) before postinst runs.
+ * - Does NOT create any users (no synouser/useradd/adduser).
+ * - Does NOT chown.
+ * - Only ensures that subdirectories (like `$SYNOPKG_PKGVAR/tmp`) exist.
+ */
+export declare function renderNativePostinst(input: NativeLifecycleInput): string;
+/**
+ * Renders `scripts/preuninst`.
+ *
+ * Requirements from N0:
+ * - Non-zero exit blocks uninstallation, so it must be best-effort (`|| true`).
+ * - Skips when `SYNOPKG_PKG_STATUS=UPGRADE`.
+ * - Calls stop via `/var/packages/${SYNOPKG_PKGNAME:-<pkg>}/scripts/start-stop-status stop`.
+ * - Does NOT use postfix stripping like `%/target`.
+ */
+export declare function renderNativePreuninst(input: NativeLifecycleInput): string;
+/**
+ * Renders `scripts/postuninst`.
+ *
+ * Shares `renderDeleteAppDataBlock` with the Compose generator so both runtimes
+ * honour the same unchecked-by-default wizard variable and the same refusal to
+ * follow a symlink out of `@appdata`. N0 showed DSM does not reclaim the
+ * package user on uninstall; deleting a system account is not this script's job.
+ */
+export declare function renderNativePostuninst(input: NativeLifecycleInput): string;

package/dist/build-spk/native-lifecycle.js

@@ -0,0 +1,205 @@
+import { renderDeleteAppDataBlock } from "./delete-app-data.js";
+import { BROKER_INSTALLER_VARS, renderBrokerStatusProbe, } from "./broker-glue.js";
+/**
+ * Escapes a literal string for safe inclusion in POSIX `/bin/sh` single quotes.
+ * A single quote is represented as `'\''` (close single quote, literal escaped single quote, reopen single quote).
+ */
+function quoteLiteral(str) {
+    return `'${str.replaceAll("'", "'\\''")}'`;
+}
+/**
+ * Escapes a token (exec path, arg, or env value) so that any `${SYNOPKG_PKGVAR}` placeholder
+ * expands safely to the shell variable `"${PKGVAR}"`, while all literal parts are securely
+ * quoted in single quotes, preventing shell injection or word splitting.
+ */
+function escapeShellTokenWithPkgvar(value, pkgvarExpr = '"${PKGVAR}"') {
+    if (value === "") {
+        return "''";
+    }
+    const placeholder = "${SYNOPKG_PKGVAR}";
+    const parts = value.split(placeholder);
+    const segments = [];
+    for (let i = 0; i < parts.length; i++) {
+        if (parts[i].length > 0) {
+            segments.push(quoteLiteral(parts[i]));
+        }
+        if (i < parts.length - 1) {
+            segments.push(pkgvarExpr);
+        }
+    }
+    return segments.length === 0 ? "''" : segments.join("");
+}
+/**
+ * Renders `conf/privilege` content.
+ * For non-container native packages, DSM accepts `{"defaults":{"run-as":"package"}}`.
+ */
+export function renderNativePrivilege() {
+    return `${JSON.stringify({
+        defaults: {
+            "run-as": "package",
+        },
+    }, null, 2)}\n`;
+}
+/**
+ * Renders `scripts/start-stop-status`.
+ *
+ * Requirements & hard facts from N0:
+ * - Start must be backgrounded via `nohup setsid ... &` because Package Center uses a oneshot unit.
+ * - PID is tracked in `$PKGVAR/<pkg>.pid`.
+ * - Status exit codes: 0 = running, 1 = PID file present but process dead, 3 = stopped / no PID file.
+ * - Fallbacks for `SYNOPKG_PKGDEST` and `SYNOPKG_PKGVAR` via `:-/var/packages/<pkg>/target` and `:-/var/packages/<pkg>/var`.
+ * - `exec` is relative to `SYNOPKG_PKGDEST` (no `target/` subfolder).
+ * - Safe quoting for `exec`, `args`, and `env`.
+ */
+export function renderNativeStartStopStatus(input) {
+    const pkg = input.packageIdentity;
+    const service = input.config.service;
+    const pkgDestFallback = `\${SYNOPKG_PKGDEST:-/var/packages/${pkg}/target}`;
+    const pkgVarFallback = `\${SYNOPKG_PKGVAR:-/var/packages/${pkg}/var}`;
+    const execToken = `"$PKGDEST/"${escapeShellTokenWithPkgvar(service.exec)}`;
+    const argTokens = (service.args ?? []).map((arg) => escapeShellTokenWithPkgvar(arg));
+    const envLines = [];
+    if (service.env) {
+        for (const [key, value] of Object.entries(service.env)) {
+            const escapedKey = quoteLiteral(key);
+            const escapedVal = escapeShellTokenWithPkgvar(value);
+            envLines.push(`    export ${escapedKey}=${escapedVal}`);
+        }
+    }
+    const envBlock = envLines.length > 0 ? `\n${envLines.join("\n")}` : "";
+    const commandLine = [execToken, ...argTokens].join(" ");
+    return `#!/bin/sh
+${BROKER_INSTALLER_VARS}
+PKGDEST="${pkgDestFallback}"
+PKGVAR="${pkgVarFallback}"
+PIDFILE="$PKGVAR/${pkg}.pid"
+LOGFILE="$PKGVAR/${pkg}.log"
+
+pid_alive() {
+  if [ ! -f "$PIDFILE" ]; then
+    return 1
+  fi
+  pid=$(cat "$PIDFILE" 2>/dev/null) || return 1
+  [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null
+}
+
+case "$1" in
+  start)
+    if pid_alive; then
+      exit 0
+    fi
+    mkdir -p "$PKGVAR"
+    rm -f "$PIDFILE"
+    (
+      cd /${envBlock}
+      nohup setsid ${commandLine} >> "$LOGFILE" 2>&1 </dev/null &
+      echo $! > "$PIDFILE"
+    )
+    # Verify the launch honestly: an exec that dies immediately (missing
+    # binary, wrong arch, bad loader) must not leave Package Center showing
+    # "started". N0 validated this re-check on hardware.
+    sleep 1
+    if pid_alive; then
+      exit 0
+    fi
+    rm -f "$PIDFILE"
+    exit 1
+    ;;
+  stop)
+    if [ -f "$PIDFILE" ]; then
+      pid=$(cat "$PIDFILE" 2>/dev/null) || pid=""
+      if [ -n "$pid" ]; then
+        if kill -0 "$pid" 2>/dev/null; then
+          kill "$pid" 2>/dev/null || true
+          n=0
+          while [ "$n" -lt 30 ]; do
+            if ! kill -0 "$pid" 2>/dev/null; then
+              break
+            fi
+            sleep 0.2
+            n=$((n + 1))
+          done
+          if kill -0 "$pid" 2>/dev/null; then
+            kill -9 "$pid" 2>/dev/null || true
+          fi
+        fi
+      fi
+      rm -f "$PIDFILE"
+    fi
+    exit 0
+    ;;
+  status)
+${renderBrokerStatusProbe(pkg)}
+    if pid_alive; then
+      exit 0
+    fi
+    if [ -f "$PIDFILE" ]; then
+      exit 1
+    fi
+    exit 3
+    ;;
+  *)
+    exit 1
+    ;;
+esac
+`;
+}
+/**
+ * Renders `scripts/postinst`.
+ *
+ * Requirements from N0:
+ * - DSM creates the package user/group and sets up `SYNOPKG_PKGVAR` (drwxr-xr-x) before postinst runs.
+ * - Does NOT create any users (no synouser/useradd/adduser).
+ * - Does NOT chown.
+ * - Only ensures that subdirectories (like `$SYNOPKG_PKGVAR/tmp`) exist.
+ */
+export function renderNativePostinst(input) {
+    const pkg = input.packageIdentity;
+    const pkgVarFallback = `\${SYNOPKG_PKGVAR:-/var/packages/${pkg}/var}`;
+    return `#!/bin/sh
+set -eu
+PKGVAR="${pkgVarFallback}"
+mkdir -p "$PKGVAR" "$PKGVAR/tmp"
+exit 0
+`;
+}
+/**
+ * Renders `scripts/preuninst`.
+ *
+ * Requirements from N0:
+ * - Non-zero exit blocks uninstallation, so it must be best-effort (`|| true`).
+ * - Skips when `SYNOPKG_PKG_STATUS=UPGRADE`.
+ * - Calls stop via `/var/packages/${SYNOPKG_PKGNAME:-<pkg>}/scripts/start-stop-status stop`.
+ * - Does NOT use postfix stripping like `%/target`.
+ */
+export function renderNativePreuninst(input) {
+    const pkg = input.packageIdentity;
+    return `#!/bin/sh
+if [ "\${SYNOPKG_PKG_STATUS:-}" = "UPGRADE" ]; then
+  exit 0
+fi
+
+CONTROL="/var/packages/\${SYNOPKG_PKGNAME:-${pkg}}/scripts/start-stop-status"
+if [ -x "$CONTROL" ]; then
+  "$CONTROL" stop 2>/dev/null || true
+fi
+exit 0
+`;
+}
+/**
+ * Renders `scripts/postuninst`.
+ *
+ * Shares `renderDeleteAppDataBlock` with the Compose generator so both runtimes
+ * honour the same unchecked-by-default wizard variable and the same refusal to
+ * follow a symlink out of `@appdata`. N0 showed DSM does not reclaim the
+ * package user on uninstall; deleting a system account is not this script's job.
+ */
+export function renderNativePostuninst(input) {
+    const pkg = input.packageIdentity;
+    const pkgVarFallback = `\${SYNOPKG_PKGVAR:-/var/packages/${pkg}/var}`;
+    return `#!/bin/sh
+set -eu
+PKGVAR="${pkgVarFallback}"
+${renderDeleteAppDataBlock(["PKGVAR"])}exit 0
+`;
+}

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

@@ -1,3 +1,18 @@
+/**
+ * Materializes one target's binary tree into `destDir`, which becomes the
+ * payload root (SYNOPKG_PKGDEST). Shared by `buildNativePayload` and by the SPK
+ * generator, which needs the tree in its own staging directory so the App
+ * Bundle files can sit alongside the binaries in a single package.tgz.
+ */
+export declare function materializeNativePayload(options: {
+    source: NativeSource;
+    projectRoot: string;
+    destDir: string;
+    download?: (url: string) => Promise<Buffer>;
+}): Promise<{
+    sourceSha256: string;
+    entries: string[];
+}>;
 export type NativeArchiveKind = "tar.gz" | "tar.xz" | "zip" | "raw";
 export interface NativeSource {
     path?: string;