@synopackageland/templates 0.10.2 → 0.10.3

package/README.md

@@ -18,7 +18,7 @@ the files an App owns; the SDK (`github.com/synopackageland/syno-pkg-land-sdk`,
 | `native-{python,node,rust}-vue` | The README and `.gitignore` of the Vue shell |
 | `binary` | A prebuilt static CGI (`example/main.go`) with a plain UI |
 | `compose` | Container Manager project (`compose.yaml`, `synology-app.yaml`) |
-| `_shared` | Agent guides, template license, Go license texts, third-party notice writer |
+| `_shared` | Agent guides, template license, Go license texts, third-party notice writer, `dsm-scripts/` (DSM lifecycle scripts) |
 
 Overlays are copied over `native-go` in the order root-ops, vue, jobs, delegate.
 An overlay may replace `internal/app/*_none.go` (the CLI deletes the matching
@@ -31,14 +31,19 @@ also makes `app.status` and `report.save` `authenticated`, and the Rust
 manifest gets the overlays' methods. `init` copies the App SDK into
 `backend/vendor` (Python `synopkgland_app`; Node `@synopackageland/app`, its
 package.json without devDependencies and scripts, and `dist/`).
+`_shared/dsm-scripts/` holds DSM's lifecycle scripts (`preinst`, `postinst`, `preupgrade`,
+`postupgrade`, `preuninst`, `postuninst`, `start-stop-status`), each commented and doing
+nothing; `init` (CLI 0.10.3 and later) copies them into every project's `dsm-scripts/`, and `build`
+calls each one from the generated script of the same name (`synopkgland skill show lifecycle`).
 The placeholders `__PACKAGE__` (also the Go module path), `__DISPLAY_NAME__` and
 `__BACKGROUND_ENABLED__` are substituted by `init`.
 
-`backend/go.mod` requires `github.com/synopackageland/syno-pkg-land-sdk v0.10.2`; that line is
+`backend/go.mod` requires `github.com/synopackageland/syno-pkg-land-sdk v0.10.3`; that line is
 the single source of the SDK version and `frontend/package.json` pins
 `@synopackageland/sdk` to the same version. Python and Node.js name it in
 `backend.sdk`, Rust in the `syno-pkg-land-app` tag of `backend/Cargo.toml`
-(and `Cargo.lock`); all of them pin 0.10.2.
+(and `Cargo.lock`); all of them pin 0.10.3. The Vue frontend pins
+`@synopackageland/ui` 0.9.5.
 
 ## Notice writer
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/templates",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "description": "Project templates for synopkgland init: native-go, native-python, native-node and native-rust (plain or Vue, with jobs, delegate and root-ops overlays), binary and compose.",
   "license": "MIT",
   "repository": {"type": "git", "url": "git+https://github.com/synopackageland/syno-pkg-land-templates.git"},

package/templates/_shared/AGENTS.md

@@ -25,6 +25,27 @@ From the project root, run `synopkgland check --json`,
 For Vue, first run `npm ci`, `npm test` and `npm run build` in frontend.
 Do not connect to or change a NAS without explicit task authorization.
 
+## Lifecycle scripts (`dsm-scripts/`)
+
+`dsm-scripts/` holds DSM's own lifecycle scripts (preinst, postinst, preupgrade,
+postupgrade, preuninst, postuninst, start-stop-status); each does nothing until
+edited. The build calls each from the generated script of the same name, as the
+package account, around the SDK's own steps. Read
+`synopkgland skill show lifecycle` before editing them; never add root work,
+never repeat SDK steps, and keep only DSM script names in that folder
+(build tools belong in `scripts/`).
+
+Root cleanup or migration after an install or upgrade (for example removing
+what an older version left in a root-owned place) is not a lifecycle script:
+name a `root/` program as `root.start` in `dsm-package.yaml`. The executor runs
+it as root once after each install or upgrade, at the first start of the new
+version and only while the administrator's approval is live; it must not
+declare `run` or `job`, should be safe to run twice, and declaring it means the
+administrator approves the App again. Package start only requests the
+executor, so `postinst`, `postupgrade` and `start` cannot wait for the step:
+keep the unprivileged follow-up in `dsm-scripts/`, and read the step's result
+from the executor `status` (`start_step`).
+
 ## Who may use the app (`entry`)
 
 Omit `entry` to keep legacy access. `entry: admin-only` admits DSM administrators
@@ -62,6 +83,27 @@ from the portal panel (`ctx.portal.register()`), which the executor's approved
 DSM resource. Beyond that, support is detected (SYNO.API.Info), not
 version-gated.
 
+### Login page look (`login_style`)
+
+A portal build gives the Login Portal entry a default look: a neutral
+wallpaper, its thumbnail in Control Panel > Login Portal > Applications, the
+login button colour `#2F6BD8`, and the App icon beside the NAS name on the
+alias login page. To use your own images, add to dsm-package.yaml (each key is
+optional; `wallpaper` and `wallpaper_thumbnail` go together):
+
+```yaml
+login_style:
+  color: "#0F766E"                                   # login button, #RGB or #RRGGBB
+  wallpaper: branding/login-wallpaper.jpg            # JPEG, at least 1920x1080, at most 2 MiB
+  wallpaper_thumbnail: branding/login-thumbnail.jpg  # JPEG 320x200, the same picture
+  title: branding/login-title.png                    # PNG 680x124, replaces icon and NAS name
+```
+
+`synopkgland check` refuses a missing image or one of the wrong format or size
+(`STANDALONE_LOGIN_STYLE_IMAGE_INVALID`) and prints the style in effect;
+`synopkgland inspect <spk>` shows what the SPK carries. Use only images you
+may redistribute; never copy Synology's.
+
 ## Background jobs (`jobs`)
 
 The worker runs the App's Work for one claimed job at a time, as the package

package/templates/_shared/dsm-scripts/postinst

@@ -0,0 +1,53 @@
+#!/bin/sh
+# postinst: runs after DSM copied the package files, at install and at the
+# install half of an upgrade (SYNOPKG_PKG_STATUS=INSTALL or UPGRADE). During an
+# upgrade, postupgrade follows it.
+#
+# Order: the SDK's postinst steps first (executor, Shared Folder, portal), then
+# this script. If the SDK steps fail, this script does not run.
+#
+# Runs as the package account, never as root. Root work belongs in root/*.sh
+# through the SDK executor (synopkgland add root-ops). Root cleanup or
+# migration after an install or upgrade is the executor's start step
+# (root.start): it runs once per new version, at the executor's first start
+# after an administrator's approval. Package start only requests the executor
+# and does not wait for it, so this script cannot see that step; keep only the
+# unprivileged follow-up here. The App reads the step's result from the
+# executor status (start_step).
+#
+# Environment (DSM sets these; the SDK passes them through unchanged):
+#   SYNOPKG_PKGNAME, SYNOPKG_PKGVER   package id and the version being installed
+#   SYNOPKG_OLD_PKGVER                the previous version (upgrade only)
+#   SYNOPKG_PKG_STATUS                INSTALL, UPGRADE, UNINSTALL, START, STOP,
+#                                     or empty at boot and shutdown
+#   SYNOPKG_PKGDEST                   installed files (/var/packages/<id>/target)
+#   SYNOPKG_PKGVAR, SYNOPKG_PKGHOME   package data and home; kept across upgrades
+#   SYNOPKG_TEMP_LOGFILE              write a message for the user here
+#   SYNOPKG_DSM_LANGUAGE              DSM language code (enu, cht, chs, jpn, ...)
+#   SYNOPKG_DSM_VERSION_MAJOR, _MINOR, _BUILD, SYNOPKG_DSM_ARCH
+#   SYNOPKG_USERNAME                  who started the action; empty when DSM did
+#
+# Install wizard answers arrive as environment variables named by each item's
+# key ("true", "false" or text). The SDK's own wizard keys are not for you.
+#
+# Exit code: 0 is success; non-zero leaves the package in a failed state
+# (DSM's own rule).
+#
+# To tell the user why something failed, write plain text to the message file
+# and exit non-zero; DSM shows it after the action:
+#   echo "Port 8080 is already in use." > "$SYNOPKG_TEMP_LOGFILE"
+#   exit 1
+#
+# Do not:
+#   - start, stop or clean up what the SDK owns (daemon, background worker,
+#     executor, portal, Shared Folder, app data deletion, uninstall.purge);
+#   - need root or try to gain it;
+#   - block for long: neither DSM nor the SDK documents a timeout, so a script
+#     that hangs blocks Package Center.
+#
+# More: synopkgland skill show lifecycle
+
+# Example: create the App's own folder in its data directory.
+# mkdir -p "$SYNOPKG_PKGVAR/cache" || exit 1
+
+exit 0

package/templates/_shared/dsm-scripts/postuninst

@@ -0,0 +1,51 @@
+#!/bin/sh
+# postuninst: runs after DSM deleted the package files. It runs at uninstall
+# (SYNOPKG_PKG_STATUS=UNINSTALL) AND during an upgrade (UPGRADE), where it is
+# the OLD version's script. SYNOPKG_PKGDEST no longer exists here.
+#
+# Order: the SDK's postuninst steps first (deleting app data when the user
+# chose it in the uninstall wizard), then this script. If the SDK steps fail,
+# this script does not run.
+#
+# Runs as the package account, never as root. Root work belongs in root/*.sh
+# through the SDK executor (synopkgland add root-ops).
+#
+# Environment (DSM sets these; the SDK passes them through unchanged):
+#   SYNOPKG_PKGNAME, SYNOPKG_PKGVER   package id and the version being installed
+#   SYNOPKG_OLD_PKGVER                the previous version (upgrade only)
+#   SYNOPKG_PKG_STATUS                INSTALL, UPGRADE, UNINSTALL, START, STOP,
+#                                     or empty at boot and shutdown
+#   SYNOPKG_PKGDEST                   installed files (/var/packages/<id>/target)
+#   SYNOPKG_PKGVAR, SYNOPKG_PKGHOME   package data and home; kept across upgrades
+#   SYNOPKG_TEMP_LOGFILE              write a message for the user here
+#   SYNOPKG_DSM_LANGUAGE              DSM language code (enu, cht, chs, jpn, ...)
+#   SYNOPKG_DSM_VERSION_MAJOR, _MINOR, _BUILD, SYNOPKG_DSM_ARCH
+#   SYNOPKG_USERNAME                  who started the action; empty when DSM did
+#
+# Uninstall wizard answers arrive as environment variables named by each
+# item's key. The SDK's uninstall wizard already asks about deleting app data.
+#
+# Exit code: DSM documents no meaning for postuninst; exit 0 unless something
+# the user must know failed.
+#
+# To tell the user why something failed, write plain text to the message file
+# and exit non-zero; DSM shows it after the action:
+#   echo "Port 8080 is already in use." > "$SYNOPKG_TEMP_LOGFILE"
+#   exit 1
+#
+# Do not:
+#   - start, stop or clean up what the SDK owns (daemon, background worker,
+#     executor, portal, Shared Folder, app data deletion, uninstall.purge);
+#   - need root or try to gain it;
+#   - block for long: neither DSM nor the SDK documents a timeout, so a script
+#     that hangs blocks Package Center.
+#
+# More: synopkgland skill show lifecycle
+
+# Example: on a real uninstall only, remove a file the App wrote outside its
+# data directories.
+# if [ "${SYNOPKG_PKG_STATUS:-}" = UNINSTALL ]; then
+#   rm -f "$SYNOPKG_PKGHOME/settings-backup.json"
+# fi
+
+exit 0

package/templates/_shared/dsm-scripts/postupgrade

@@ -0,0 +1,54 @@
+#!/bin/sh
+# postupgrade: runs at the end of an upgrade, after the new postinst
+# (SYNOPKG_PKG_STATUS=UPGRADE). It is the NEW version's script.
+#
+# Order: the SDK's postupgrade steps first, then this script. If the SDK steps
+# fail, this script does not run.
+#
+# Runs as the package account, never as root. Root work belongs in root/*.sh
+# through the SDK executor (synopkgland add root-ops). Root cleanup or
+# migration after an install or upgrade is the executor's start step
+# (root.start): it runs once per new version, at the executor's first start
+# after an administrator's approval. Package start only requests the executor
+# and does not wait for it, so this script cannot see that step; keep only the
+# unprivileged follow-up here. The App reads the step's result from the
+# executor status (start_step).
+#
+# Environment (DSM sets these; the SDK passes them through unchanged):
+#   SYNOPKG_PKGNAME, SYNOPKG_PKGVER   package id and the version being installed
+#   SYNOPKG_OLD_PKGVER                the previous version (upgrade only)
+#   SYNOPKG_PKG_STATUS                INSTALL, UPGRADE, UNINSTALL, START, STOP,
+#                                     or empty at boot and shutdown
+#   SYNOPKG_PKGDEST                   installed files (/var/packages/<id>/target)
+#   SYNOPKG_PKGVAR, SYNOPKG_PKGHOME   package data and home; kept across upgrades
+#   SYNOPKG_TEMP_LOGFILE              write a message for the user here
+#   SYNOPKG_DSM_LANGUAGE              DSM language code (enu, cht, chs, jpn, ...)
+#   SYNOPKG_DSM_VERSION_MAJOR, _MINOR, _BUILD, SYNOPKG_DSM_ARCH
+#   SYNOPKG_USERNAME                  who started the action; empty when DSM did
+#
+# Upgrade wizard answers arrive as environment variables named by each item's
+# key. A silent upgrade shows no wizard, so always have a default.
+#
+# Exit code: 0 is success; non-zero leaves the package in a failed state
+# (DSM's own rule).
+#
+# To tell the user why something failed, write plain text to the message file
+# and exit non-zero; DSM shows it after the action:
+#   echo "Port 8080 is already in use." > "$SYNOPKG_TEMP_LOGFILE"
+#   exit 1
+#
+# Do not:
+#   - start, stop or clean up what the SDK owns (daemon, background worker,
+#     executor, portal, Shared Folder, app data deletion, uninstall.purge);
+#   - need root or try to gain it;
+#   - block for long: neither DSM nor the SDK documents a timeout, so a script
+#     that hangs blocks Package Center.
+#
+# More: synopkgland skill show lifecycle
+
+# Example: migrate the App's data once, from versions before 1.2.
+# case "${SYNOPKG_OLD_PKGVER:-}" in
+#   0.*|1.0*|1.1*) "$SYNOPKG_PKGDEST/app/migrate" || exit 1 ;;
+# esac
+
+exit 0

package/templates/_shared/dsm-scripts/preinst

@@ -0,0 +1,49 @@
+#!/bin/sh
+# preinst: runs before DSM copies the package files, at install and at the
+# install half of an upgrade (SYNOPKG_PKG_STATUS=INSTALL or UPGRADE).
+#
+# Order: the SDK's preinst steps first, then this script. If the SDK steps
+# fail, this script does not run.
+#
+# Runs as the package account, never as root. Root work belongs in root/*.sh
+# through the SDK executor (synopkgland add root-ops).
+#
+# Environment (DSM sets these; the SDK passes them through unchanged):
+#   SYNOPKG_PKGNAME, SYNOPKG_PKGVER   package id and the version being installed
+#   SYNOPKG_OLD_PKGVER                the previous version (upgrade only)
+#   SYNOPKG_PKG_STATUS                INSTALL, UPGRADE, UNINSTALL, START, STOP,
+#                                     or empty at boot and shutdown
+#   SYNOPKG_PKGDEST                   installed files (/var/packages/<id>/target)
+#   SYNOPKG_PKGVAR, SYNOPKG_PKGHOME   package data and home; kept across upgrades
+#   SYNOPKG_TEMP_LOGFILE              write a message for the user here
+#   SYNOPKG_DSM_LANGUAGE              DSM language code (enu, cht, chs, jpn, ...)
+#   SYNOPKG_DSM_VERSION_MAJOR, _MINOR, _BUILD, SYNOPKG_DSM_ARCH
+#   SYNOPKG_USERNAME                  who started the action; empty when DSM did
+#
+# Install wizard answers arrive as environment variables named by each item's
+# key ("true", "false" or text). The SDK's own wizard keys are not for you.
+#
+# Exit code: 0 continues; non-zero aborts the install or upgrade (DSM's own
+# rule). Keep this to checks: nothing undoes a change made here.
+#
+# To tell the user why something failed, write plain text to the message file
+# and exit non-zero; DSM shows it after the action:
+#   echo "Port 8080 is already in use." > "$SYNOPKG_TEMP_LOGFILE"
+#   exit 1
+#
+# Do not:
+#   - start, stop or clean up what the SDK owns (daemon, background worker,
+#     executor, portal, Shared Folder, app data deletion, uninstall.purge);
+#   - need root or try to gain it;
+#   - block for long: neither DSM nor the SDK documents a timeout, so a script
+#     that hangs blocks Package Center.
+#
+# More: synopkgland skill show lifecycle
+
+# Example: refuse DSM older than 7.2.
+# if [ "${SYNOPKG_DSM_VERSION_MAJOR:-7}" -eq 7 ] && [ "${SYNOPKG_DSM_VERSION_MINOR:-0}" -lt 2 ]; then
+#   echo "This App needs DSM 7.2 or later." > "$SYNOPKG_TEMP_LOGFILE"
+#   exit 1
+# fi
+
+exit 0

package/templates/_shared/dsm-scripts/preuninst

@@ -0,0 +1,50 @@
+#!/bin/sh
+# preuninst: runs before DSM deletes the package files, after DSM stopped the
+# package. It runs at uninstall (SYNOPKG_PKG_STATUS=UNINSTALL) AND during an
+# upgrade (UPGRADE), where it is the OLD version's script.
+#
+# Order: this script first, then the SDK's preuninst steps (stop, the App's
+# uninstall.purge, executor cleanup).
+#
+# Runs as the package account, never as root. Root work belongs in root/*.sh
+# through the SDK executor (synopkgland add root-ops).
+#
+# Environment (DSM sets these; the SDK passes them through unchanged):
+#   SYNOPKG_PKGNAME, SYNOPKG_PKGVER   package id and the version being installed
+#   SYNOPKG_OLD_PKGVER                the previous version (upgrade only)
+#   SYNOPKG_PKG_STATUS                INSTALL, UPGRADE, UNINSTALL, START, STOP,
+#                                     or empty at boot and shutdown
+#   SYNOPKG_PKGDEST                   installed files (/var/packages/<id>/target)
+#   SYNOPKG_PKGVAR, SYNOPKG_PKGHOME   package data and home; kept across upgrades
+#   SYNOPKG_TEMP_LOGFILE              write a message for the user here
+#   SYNOPKG_DSM_LANGUAGE              DSM language code (enu, cht, chs, jpn, ...)
+#   SYNOPKG_DSM_VERSION_MAJOR, _MINOR, _BUILD, SYNOPKG_DSM_ARCH
+#   SYNOPKG_USERNAME                  who started the action; empty when DSM did
+#
+# Uninstall wizard answers arrive as environment variables named by each
+# item's key. The SDK's uninstall wizard already asks about deleting app data.
+#
+# Exit code: 0 continues; non-zero aborts the uninstall or upgrade before the
+# SDK steps run (DSM's own rule).
+#
+# To tell the user why something failed, write plain text to the message file
+# and exit non-zero; DSM shows it after the action:
+#   echo "Port 8080 is already in use." > "$SYNOPKG_TEMP_LOGFILE"
+#   exit 1
+#
+# Do not:
+#   - start, stop or clean up what the SDK owns (daemon, background worker,
+#     executor, portal, Shared Folder, app data deletion, uninstall.purge);
+#   - need root or try to gain it;
+#   - block for long: neither DSM nor the SDK documents a timeout, so a script
+#     that hangs blocks Package Center.
+#
+# More: synopkgland skill show lifecycle
+
+# Example: on a real uninstall only, export the App's settings to a file the
+# user keeps.
+# if [ "${SYNOPKG_PKG_STATUS:-}" = UNINSTALL ]; then
+#   cp "$SYNOPKG_PKGVAR/settings.json" "$SYNOPKG_PKGHOME/settings-backup.json" 2>/dev/null || true
+# fi
+
+exit 0

package/templates/_shared/dsm-scripts/preupgrade

@@ -0,0 +1,52 @@
+#!/bin/sh
+# preupgrade: runs at the start of an upgrade, after DSM stopped the old
+# version (SYNOPKG_PKG_STATUS=UPGRADE). It is the NEW version's script, but
+# SYNOPKG_PKGDEST still holds the OLD version's files.
+#
+# Upgrade order: old start-stop-status stop, new preupgrade, old preuninst,
+# old files deleted, old postuninst, new preinst, new files, new postinst,
+# new postupgrade, new start-stop-status start.
+#
+# Order in this script: this script first, then the SDK's preupgrade steps.
+#
+# Runs as the package account, never as root. Root work belongs in root/*.sh
+# through the SDK executor (synopkgland add root-ops).
+#
+# Environment (DSM sets these; the SDK passes them through unchanged):
+#   SYNOPKG_PKGNAME, SYNOPKG_PKGVER   package id and the version being installed
+#   SYNOPKG_OLD_PKGVER                the previous version (upgrade only)
+#   SYNOPKG_PKG_STATUS                INSTALL, UPGRADE, UNINSTALL, START, STOP,
+#                                     or empty at boot and shutdown
+#   SYNOPKG_PKGDEST                   installed files (/var/packages/<id>/target)
+#   SYNOPKG_PKGVAR, SYNOPKG_PKGHOME   package data and home; kept across upgrades
+#   SYNOPKG_TEMP_LOGFILE              write a message for the user here
+#   SYNOPKG_DSM_LANGUAGE              DSM language code (enu, cht, chs, jpn, ...)
+#   SYNOPKG_DSM_VERSION_MAJOR, _MINOR, _BUILD, SYNOPKG_DSM_ARCH
+#   SYNOPKG_USERNAME                  who started the action; empty when DSM did
+#
+# Upgrade wizard answers arrive as environment variables named by each item's
+# key. A silent upgrade shows no wizard, so always have a default.
+#
+# Exit code: 0 continues; non-zero aborts the upgrade before the SDK steps run
+# (DSM's own rule). Keep this to checks and to saving what postupgrade needs.
+#
+# To tell the user why something failed, write plain text to the message file
+# and exit non-zero; DSM shows it after the action:
+#   echo "Port 8080 is already in use." > "$SYNOPKG_TEMP_LOGFILE"
+#   exit 1
+#
+# Do not:
+#   - start, stop or clean up what the SDK owns (daemon, background worker,
+#     executor, portal, Shared Folder, app data deletion, uninstall.purge);
+#   - need root or try to gain it;
+#   - block for long: neither DSM nor the SDK documents a timeout, so a script
+#     that hangs blocks Package Center.
+#
+# More: synopkgland skill show lifecycle
+
+# Example: refuse a downgrade the App's data format cannot take.
+# case "${SYNOPKG_OLD_PKGVER:-}" in
+#   2.*) echo "Downgrading from 2.x is not supported." > "$SYNOPKG_TEMP_LOGFILE"; exit 1 ;;
+# esac
+
+exit 0

package/templates/_shared/dsm-scripts/start-stop-status

@@ -0,0 +1,59 @@
+#!/bin/sh
+# start-stop-status: DSM calls it with one argument:
+#   start     the user started the package, at boot, or after install/upgrade
+#   stop      the user stopped it, at shutdown, before upgrade and uninstall
+#   status    DSM asks whether the package runs
+#   prestart, prestop  only when INFO has precheckstartstop (the SDK sets it
+#             for daemon and background-job Apps); non-zero refuses the action
+#
+# Order: start, prestart and status run the SDK steps first, then this script.
+# stop and prestop run this script first, then the SDK steps; the SDK stop
+# always runs. If this script fails at start, the SDK stops again.
+# SYNOPKG_PKG_STATUS tells why (START, STOP, INSTALL, UPGRADE, UNINSTALL, or
+# empty at boot and shutdown).
+#
+# Runs as the package account, never as root. Root work belongs in root/*.sh
+# through the SDK executor (synopkgland add root-ops).
+#
+# Environment (DSM sets these; the SDK passes them through unchanged):
+#   SYNOPKG_PKGNAME, SYNOPKG_PKGVER   package id and the version being installed
+#   SYNOPKG_OLD_PKGVER                the previous version (upgrade only)
+#   SYNOPKG_PKG_STATUS                INSTALL, UPGRADE, UNINSTALL, START, STOP,
+#                                     or empty at boot and shutdown
+#   SYNOPKG_PKGDEST                   installed files (/var/packages/<id>/target)
+#   SYNOPKG_PKGVAR, SYNOPKG_PKGHOME   package data and home; kept across upgrades
+#   SYNOPKG_TEMP_LOGFILE              write a message for the user here
+#   SYNOPKG_DSM_LANGUAGE              DSM language code (enu, cht, chs, jpn, ...)
+#   SYNOPKG_DSM_VERSION_MAJOR, _MINOR, _BUILD, SYNOPKG_DSM_ARCH
+#   SYNOPKG_USERNAME                  who started the action; empty when DSM did
+#
+# Exit code: for start and stop, 0 is success and non-zero a failure. For
+# status, the SDK asks this script only while the SDK runs: 0 running,
+# 3 not running, 4 unknown, 150 broken (DSM's own codes).
+#
+# To tell the user why something failed, write plain text to the message file
+# and exit non-zero; DSM shows it after the action:
+#   echo "Port 8080 is already in use." > "$SYNOPKG_TEMP_LOGFILE"
+#   exit 1
+#
+# Do not:
+#   - start, stop or clean up what the SDK owns (daemon, background worker,
+#     executor, portal, Shared Folder, app data deletion, uninstall.purge);
+#   - need root or try to gain it;
+#   - block for long: neither DSM nor the SDK documents a timeout, so a script
+#     that hangs blocks Package Center.
+#
+# More: synopkgland skill show lifecycle
+
+case "$1" in
+  start)
+    # Example: refuse to start without a setting the App needs.
+    # if [ ! -s "$SYNOPKG_PKGVAR/settings.json" ]; then
+    #   echo "Open the App once to finish its setup." > "$SYNOPKG_TEMP_LOGFILE"
+    #   exit 1
+    # fi
+    exit 0 ;;
+  stop) exit 0 ;;
+  status) exit 0 ;;
+  *) exit 0 ;;
+esac

package/templates/native-go/README.md

@@ -315,12 +315,28 @@ A portal needs DSM 7.3.2-86009 or later, so `add portal` raises a lower
 package that registers a portal (Package Center error 320); 7.3.2 and 7.4
 install it; 7.2 is untested. To keep supporting older DSM, remove `portal:`.
 
+The build also gives the portal a login page look: a neutral default
+wallpaper (its thumbnail is what Control Panel > Login Portal > Applications
+shows), a button colour and the App icon. Replace them with your own in
+dsm-package.yaml:
+
+```yaml
+login_style:
+  color: "#0F766E"                                   # login button
+  wallpaper: branding/login-wallpaper.jpg            # JPEG, at least 1920x1080, at most 2 MiB
+  wallpaper_thumbnail: branding/login-thumbnail.jpg  # JPEG 320x200; required with wallpaper
+  title: branding/login-title.png                    # PNG 680x124, in place of icon and NAS name
+```
+
+`synopkgland check` validates the files and prints the style in effect.
+
 ## Data, upgrades, uninstall
 
 The backend stores data in `/var/packages/__PACKAGE__/var` (the package's
 own folder, kept across upgrades). Bump `build` for every SPK you hand out;
-bump `version` for feature releases. There are no lifecycle scripts to write:
-the CGI starts per request, so start/stop do nothing.
+bump `version` for feature releases. You need no lifecycle scripts: the CGI
+starts per request, so start/stop do nothing. For extra install, upgrade or
+uninstall work, edit `dsm-scripts/` (`synopkgland skill show lifecycle`).
 
 ### What an upgrade keeps
 

package/templates/native-go/backend/THIRD_PARTY_NOTICES.txt

@@ -1,6 +1,6 @@
 Native Go package build dependencies
 
-github.com/synopackageland/syno-pkg-land-sdk v0.10.2 (MIT)
+github.com/synopackageland/syno-pkg-land-sdk v0.10.3 (MIT)
 
 Copyright (c) 2026 synopkgland
 

package/templates/native-go/backend/cmd/app/main.go

@@ -42,16 +42,16 @@ var (
 	// "on" when dsm-package.yaml declares portal: serves portal.status;
 	// "executor" below DSM 7.2, where the executor registers the entry.
 	portal = ""
-	// backend.timeout_seconds, 60 unless set.
+	// backend.timeout_seconds, api.DefaultRequestTimeout unless set.
 	requestTimeout = ""
 )
 
-// deadline is the CGI request deadline: requestTimeout seconds, or 60 when it
-// is unset or not a positive number.
+// deadline is the CGI request deadline: requestTimeout seconds, or
+// api.DefaultRequestTimeout when it is unset or not a positive number.
 func deadline() api.DeadlineOption {
 	seconds, err := strconv.Atoi(requestTimeout)
 	if err != nil || seconds <= 0 {
-		seconds = 60
+		return api.Timeout(api.DefaultRequestTimeout)
 	}
 	return api.Timeout(time.Duration(seconds) * time.Second)
 }

package/templates/native-go/backend/cmd/app/main_test.go

@@ -13,12 +13,12 @@ func TestRequestDeadlineFollowsTheBuildSetting(t *testing.T) {
 	saved := requestTimeout
 	t.Cleanup(func() { requestTimeout = saved })
 	for setting, want := range map[string]time.Duration{
-		"":    60 * time.Second,
+		"":    api.DefaultRequestTimeout,
 		"120": 120 * time.Second,
 		"1":   time.Second,
-		"0":   60 * time.Second,
-		"-5":  60 * time.Second,
-		"x":   60 * time.Second,
+		"0":   api.DefaultRequestTimeout,
+		"-5":  api.DefaultRequestTimeout,
+		"x":   api.DefaultRequestTimeout,
 	} {
 		requestTimeout = setting
 		var left time.Duration

package/templates/native-go/backend/go.mod

@@ -4,6 +4,6 @@ go 1.25.0
 
 toolchain go1.26.9
 
-require github.com/synopackageland/syno-pkg-land-sdk v0.10.2
+require github.com/synopackageland/syno-pkg-land-sdk v0.10.3
 
 require golang.org/x/sys v0.44.0 // indirect

package/templates/native-go/backend/go.sum

@@ -1,4 +1,4 @@
-github.com/synopackageland/syno-pkg-land-sdk v0.10.2 h1:2sQTuKCkwbFk5vnnY+21N3xIBKu7D8PVydgwxmIeGWI=
-github.com/synopackageland/syno-pkg-land-sdk v0.10.2/go.mod h1:hlsvaVuH2wsAoR8jzI1Rg/NeejQSFpAaN6zpIWsVbjI=
+github.com/synopackageland/syno-pkg-land-sdk v0.10.3 h1:YMwtSPqR7sS6pGKF0x7vMoMxNSY7GIMcxTa++VCTlz8=
+github.com/synopackageland/syno-pkg-land-sdk v0.10.3/go.mod h1:hlsvaVuH2wsAoR8jzI1Rg/NeejQSFpAaN6zpIWsVbjI=
 golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
 golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=

package/templates/native-go-delegate/frontend/test/capability-panels.test.ts

@@ -29,7 +29,7 @@ test('the capability surface uses an explicit long-running facade without legacy
  } satisfies BackgroundSaveFacade
  const call=vi.fn(async()=>{throw {code:'unexpected-legacy-call'}})
  const root=render({delegate:sdk,call,locale:'en'});await settle()
- expect(root.textContent).toContain('My destinations');expect(root.textContent).toContain('/home/Exports')
+ expect(root.textContent).toContain('My saves');expect(sdk.operations).toHaveBeenCalled()
  expect(call).not.toHaveBeenCalled()
 })
 test('the default surface binds the real routes and the session-only picker',async()=>{
@@ -46,12 +46,12 @@ test('the default surface binds the real routes and the session-only picker',asy
   throw {code:'unexpected'}
  })
  const root=render({call,locale:'en'});await settle()
- button(root,'Choose save destination').click();await settle()
+ button(root,'Choose folder').click();await settle()
  // The SDK picker selects a folder with a row click.
  const row=root.querySelector<HTMLElement>('tr[data-row-key="/home"]')!;expect(row).toBeTruthy();row.dispatchEvent(new MouseEvent('click',{bubbles:true}));await settle()
  button(root,'Confirm selection').click();await settle()
  expect(call).toHaveBeenCalledWith('delegate.select_destination',{key:'save',path:'/home'})
- // The template demonstrates the save flow; SDK 0.9.9 shows it only on request.
+ // The SDK hides the sample save unless an App opts in; the template opts in with sample-save.
  button(root,'Save example file').click();await settle()
  expect(call).toHaveBeenCalledWith('delegate.example.export',expect.objectContaining({key:'save'}))
 })

package/templates/native-go-root-ops/backend/internal/app/executor.go

@@ -6,7 +6,6 @@ import (
 	"errors"
 	"net/http"
 	"path/filepath"
-	"time"
 
 	"github.com/synopackageland/syno-pkg-land-sdk/api"
 	"github.com/synopackageland/syno-pkg-land-sdk/delegate"
@@ -59,7 +58,8 @@ func (cfg Config) executorHoldsThisBuild(ctx context.Context) error {
 var executorSocketBase = "/run/synopkgland"
 
 // executor keeps the executor's protocol v1 refusal codes (POLICY_DENIED,
-// EXECUTOR_UNAVAILABLE, ...) as the API error code.
+// EXECUTOR_UNAVAILABLE, ...) as the API error code. Without its own Timeout
+// the client waits as the SDK says: delegate.ExecutorTimeout, root.run longer.
 func (cfg Config) executor() *delegate.Client {
-	return &delegate.Client{Socket: filepath.Join(executorSocketBase, cfg.PackageID, "executor.sock"), Timeout: 30 * time.Second}
+	return &delegate.Client{Socket: filepath.Join(executorSocketBase, cfg.PackageID, "executor.sock")}
 }

package/templates/native-go-root-ops/backend/internal/app/executor_test.go

@@ -163,3 +163,11 @@ func TestExecutorRootRunReportsTheExecutorsRefusalCode(t *testing.T) {
 		}
 	}
 }
+
+// The executor client waits as long as the SDK says (spec/protocol/v1,
+// Timeouts): delegate.ExecutorTimeout for status and control, root.run longer.
+func TestTheExecutorClientWaitsTheSDKsTimeout(t *testing.T) {
+	if got := testConfig(t).executor().Timeout; got != 0 {
+		t.Fatalf("executor client sets its own wait %v instead of the SDK's", got)
+	}
+}

package/templates/native-go-vue/README.md

@@ -29,6 +29,9 @@ and the background picker uses the retained session provider.
 With `portal:` declared (`synopkgland add portal`, executor Apps only), the status page shows
 the SDK's `PortalSettings`: the DSM Application Portal link, the alias form
 for administrators, and the Control Panel shortcut.
+The alias login page's wallpaper, button colour and title come from
+`login_style:` in dsm-package.yaml (a default otherwise); see
+`synopkgland skill show portal`.
 
 Use public library controls, the embedded theme, per-app modal scope and unique
 Vue ID prefixes. Backend route permissions and DSM checks remain authoritative.

package/templates/native-go-vue/frontend/package-lock.json

@@ -7,8 +7,8 @@
       "name": "native-dsm-vue-app",
       "dependencies": {
         "@lucide/vue": "1.48.0",
-        "@synopackageland/sdk": "0.10.2",
-        "@synopackageland/ui": "0.9.4",
+        "@synopackageland/sdk": "0.10.3",
+        "@synopackageland/ui": "0.9.5",
         "vue": "3.5.43"
       },
       "devDependencies": {
@@ -1148,13 +1148,13 @@
       }
     },
     "node_modules/@synopackageland/sdk": {
-      "version": "0.10.2",
-      "resolved": "https://registry.npmjs.org/@synopackageland/sdk/-/sdk-0.10.2.tgz",
-      "integrity": "sha512-ZX854q5grp/dpCFze/JxmbWS/a6CKOGA8YpgXutMrY807G1JU0PGlfAeeQ4zQ37vZ741VNgOUEo9x5hZDdSB+w==",
+      "version": "0.10.3",
+      "resolved": "https://registry.npmjs.org/@synopackageland/sdk/-/sdk-0.10.3.tgz",
+      "integrity": "sha512-1YsPAtNm4azqCEhAUv/99o10dxwXMtjOg4aRKnwbrSpjrOYQrhsGKfyFj9bFimqIGy0mj2NvRPKGz8ET0HqyEg==",
       "license": "MIT",
       "peerDependencies": {
         "@lucide/vue": "^1.48.0",
-        "@synopackageland/ui": "^0.9.4",
+        "@synopackageland/ui": "^0.9.5",
         "vue": "^3.5.0"
       },
       "peerDependenciesMeta": {
@@ -1167,9 +1167,9 @@
       }
     },
     "node_modules/@synopackageland/ui": {
-      "version": "0.9.4",
-      "resolved": "https://registry.npmjs.org/@synopackageland/ui/-/ui-0.9.4.tgz",
-      "integrity": "sha512-yu0RrYtT/QcAn/lNwqZBoqqjLTXrpqqnSWB+0swGou8IWLrhfwXrHVBf+oJc+NjLj+G4kB7AyP9kbvw9FHxNOA==",
+      "version": "0.9.5",
+      "resolved": "https://registry.npmjs.org/@synopackageland/ui/-/ui-0.9.5.tgz",
+      "integrity": "sha512-fytttAWLZ48H0w5UYsDzfJu7I4yBmafFviMoku+WZtwroNm6z26gTBdCgkg9a5MmxghFU8e1p5NWYnKfVVPbEw==",
       "license": "MIT",
       "dependencies": {
         "@internationalized/date": "3.12.4",

package/templates/native-go-vue/frontend/package.json

@@ -8,8 +8,8 @@
   },
   "dependencies": {
     "@lucide/vue": "1.48.0",
-    "@synopackageland/sdk": "0.10.2",
-    "@synopackageland/ui": "0.9.4",
+    "@synopackageland/sdk": "0.10.3",
+    "@synopackageland/ui": "0.9.5",
     "vue": "3.5.43"
   },
   "devDependencies": {

package/templates/native-go-vue/frontend/src/i18n/zh-CN.json

@@ -11,7 +11,7 @@
   "errors": {
     "session_required": "DSM 登录已过期，请重新登录。",
     "admin_required": "此操作必须由 DSM 管理员执行。",
-    "app_privilege_denied": "DSM 应用程序权限不允许此帐户使用此 App。",
+    "app_privilege_denied": "DSM 应用程序权限不允许此账户使用此 App。",
     "auth_unavailable": "DSM 验证暂时不可用，请刷新后重试。",
     "request_failed": "请求失败（{code}），请刷新后重试。"
   }

package/templates/native-node/README.md

@@ -119,6 +119,13 @@ A service refuses with its own code (`limit_exceeded`, `read_failed`, the
 executor's refusals); the examples pass it on to the browser. `synopkgland add`
 works on Go backends only: start a Node.js App with the capabilities it needs.
 
+With `portal:` in dsm-package.yaml (executor Apps only, see
+`synopkgland skill show portal`), the build also gives the Login Portal entry a
+default wallpaper, thumbnail, button colour and the App icon. `login_style:`
+replaces them: `color`, `wallpaper` (JPEG, at least 1920x1080) with
+`wallpaper_thumbnail` (JPEG 320x200), and `title` (PNG 680x124); `synopkgland
+check` validates the files.
+
 ## The SDK
 
 `backend.sdk` in dsm-package.yaml names the SDK release: the build ships its runtime and its Node SDK as `backend/app/node_modules/@synopackageland/app`, and reads the method list from `main.js --describe`. `backend/vendor/@synopackageland/app` is the same SDK for tests and type checks; replace it with the new release's when you change `backend.sdk`. Upgrade the SDK by changing that version; `synopkgland check`

package/templates/native-node/dsm-package.yaml

@@ -49,7 +49,7 @@ backend:
   runtime: node
   dir: backend/app
   entry: main.js
-  sdk: 0.10.2
+  sdk: 0.10.3
   node: { package: Node.js_v20 }
 
 ui:

package/templates/native-python/README.md

@@ -116,6 +116,13 @@ A service refuses with its own code (`limit_exceeded`, `read_failed`, the
 executor's refusals); the examples pass it on to the browser. `synopkgland add`
 works on Go backends only: start a Python App with the capabilities it needs.
 
+With `portal:` in dsm-package.yaml (executor Apps only, see
+`synopkgland skill show portal`), the build also gives the Login Portal entry a
+default wallpaper, thumbnail, button colour and the App icon. `login_style:`
+replaces them: `color`, `wallpaper` (JPEG, at least 1920x1080) with
+`wallpaper_thumbnail` (JPEG 320x200), and `title` (PNG 680x124); `synopkgland
+check` validates the files.
+
 ## The SDK
 
 `backend.sdk` in dsm-package.yaml names the SDK release: the build ships its runtime and its Python SDK as `backend/app/vendor/synopkgland_app`, and reads the method list from `main.py --describe`. `backend/vendor/synopkgland_app` is the same SDK for tests; replace it with the new release's when you change `backend.sdk`. Upgrade the SDK by changing that version; `synopkgland check`

package/templates/native-python/dsm-package.yaml

@@ -47,7 +47,7 @@ backend:
   runtime: python
   dir: backend/app
   entry: main.py
-  sdk: 0.10.2
+  sdk: 0.10.3
 
 ui:
   # Static files served at /webman/3rdparty/<package>/app/. app.js and app.css

package/templates/native-rust/README.md

@@ -125,6 +125,13 @@ A service refuses with its own code (`limit_exceeded`, `read_failed`, the
 executor's refusals); the examples pass it on to the browser. `synopkgland add`
 works on Go backends only: start a Rust App with the capabilities it needs.
 
+With `portal:` in dsm-package.yaml (executor Apps only, see
+`synopkgland skill show portal`), the build also gives the Login Portal entry a
+default wallpaper, thumbnail, button colour and the App icon. `login_style:`
+replaces them: `color`, `wallpaper` (JPEG, at least 1920x1080) with
+`wallpaper_thumbnail` (JPEG 320x200), and `title` (PNG 680x124); `synopkgland
+check` validates the files.
+
 ## The SDK
 
 The `syno-pkg-land-app` git dependency's `tag` in `backend/Cargo.toml` names the SDK release; the build reads it from `Cargo.lock` and ships that release's runtime. A cross-compiled binary cannot run on the build machine, so `backend.methods` in dsm-package.yaml lists every method the App registers; `synopkgland check` refuses a list that differs from the App's own. Upgrade the SDK by changing that version; `synopkgland check`

package/templates/native-rust/backend/Cargo.lock

@@ -104,8 +104,8 @@ dependencies = [
 
 [[package]]
 name = "syno-pkg-land-app"
-version = "0.10.2"
-source = "git+https://github.com/synopackageland/syno-pkg-land-sdk?tag=v0.10.2#3255e7ef0cfdfc89ae1308bfe1ddf2eabfe6f1b6"
+version = "0.10.3"
+source = "git+https://github.com/synopackageland/syno-pkg-land-sdk?tag=v0.10.3#4e0fe8ee1f71a9818e50a38242882cebaa776cee"
 dependencies = [
  "libc",
  "serde",

package/templates/native-rust/backend/Cargo.toml

@@ -9,7 +9,7 @@ libc = "0.2"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 # The SDK version is the tag; `synopkgland check` reads it from Cargo.lock.
-syno-pkg-land-app = { git = "https://github.com/synopackageland/syno-pkg-land-sdk", tag = "v0.10.2" }
+syno-pkg-land-app = { git = "https://github.com/synopackageland/syno-pkg-land-sdk", tag = "v0.10.3" }
 
 [profile.release]
 # A handler panic becomes an "internal" reply; abort would end the App without one.