@synopackageland/cli 0.4.0 → 0.5.0

package/templates/_gateway/groups.go

@@ -0,0 +1,66 @@
+package main
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"os"
+	"slices"
+	"strings"
+)
+
+// groupsOf reads local group files fresh on each request. Directory accounts
+// use NSS afresh; DSM provider caching may delay directory membership changes.
+// DSM keeps no member list for the group
+// that is an account's primary group (users), so membership is the member
+// list or the primary gid from the passwd file. Accounts absent from passwd use
+// DSM NSS; no local member-list fallback is permitted on lookup failure.
+func (a *dsmAuthenticator) groupsOf(ctx context.Context, user string) ([]string, error) {
+	primary, err := a.primaryGID(user)
+	if err != nil {
+		return nil, err
+	}
+	if primary == "" {
+		if a.directoryGroups == nil {
+			return nil, fmt.Errorf("directory group lookup unavailable")
+		}
+		return a.directoryGroups(ctx, user)
+	}
+	f, err := os.Open(a.groupFile)
+	if err != nil {
+		return nil, fmt.Errorf("read groups: %w", err)
+	}
+	defer f.Close()
+	var groups []string
+	scanner := bufio.NewScanner(f)
+	for scanner.Scan() {
+		fields := strings.Split(scanner.Text(), ":")
+		if len(fields) == 4 && (fields[2] == primary || slices.Contains(strings.Split(fields[3], ","), user)) {
+			groups = append(groups, fields[0])
+		}
+	}
+	if err := scanner.Err(); err != nil {
+		return nil, fmt.Errorf("read groups: %w", err)
+	}
+	return groups, nil
+}
+
+// primaryGID is the account's gid in the passwd file; "" when the account has
+// no local entry, which requires a fresh directory lookup.
+func (a *dsmAuthenticator) primaryGID(user string) (string, error) {
+	f, err := os.Open(a.passwdFile)
+	if err != nil {
+		return "", fmt.Errorf("read accounts: %w", err)
+	}
+	defer f.Close()
+	scanner := bufio.NewScanner(f)
+	for scanner.Scan() {
+		if fields := strings.Split(scanner.Text(), ":"); len(fields) >= 4 && fields[0] == user {
+			return fields[3], nil
+		}
+	}
+	if err := scanner.Err(); err != nil {
+		return "", fmt.Errorf("read accounts: %w", err)
+	}
+	return "", nil
+}

package/templates/_gateway/main.go

@@ -0,0 +1,45 @@
+// Command gateway is the DSM-authenticated front door of a container package.
+// DSM runs it as a CGI (ui/cgi/gateway.cgi in the package) under the package
+// account, once per request.
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http/cgi"
+	"os"
+)
+
+// Set by `synopkgland build-spk` through -ldflags -X; never read from a request.
+var (
+	packageID  = "dev"
+	configJSON = ""
+)
+
+func main() {
+	log.SetFlags(0)
+	log.SetPrefix(packageID + ": ")
+	if os.Getenv("GATEWAY_INTERFACE") == "" {
+		fmt.Fprintf(os.Stderr, "%s: this program runs as the package's DSM CGI; open the app from the DSM main menu.\n", packageID)
+		os.Exit(2)
+	}
+	var cfg config
+	decoder := json.NewDecoder(bytes.NewReader([]byte(configJSON)))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&cfg); err != nil {
+		log.Fatalf("invalid gateway configuration: %v", err)
+	}
+	g, err := newGateway(cfg, newDSMAuthenticator())
+	if err != nil {
+		log.Fatal(err)
+	}
+	req, err := cgi.Request()
+	if err != nil {
+		log.Fatal(err)
+	}
+	if err := serveCGI(g, req, os.Stdin, os.Stdout); err != nil {
+		log.Fatal(err)
+	}
+}

package/templates/_shared/GO-LICENSE

@@ -0,0 +1,27 @@
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/templates/_shared/GO-PATENTS

@@ -0,0 +1,22 @@
+Additional IP Rights Grant (Patents)
+
+"This implementation" means the copyrightable works distributed by
+Google as part of the Go project.
+
+Google hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section)
+patent license to make, have made, use, offer to sell, sell, import,
+transfer and otherwise run, modify and propagate the contents of this
+implementation of Go, where such license applies only to those patent
+claims, both currently owned or controlled by Google and acquired in
+the future, licensable by Google that are necessarily infringed by this
+implementation of Go.  This grant does not include claims that would be
+infringed only as a consequence of further modification of this
+implementation.  If you or your agent or exclusive licensee institute or
+order or agree to the institution of patent litigation against any
+entity (including a cross-claim or counterclaim in a lawsuit) alleging
+that this implementation of Go or any code incorporated within this
+implementation of Go constitutes direct or contributory patent
+infringement, or inducement of patent infringement, then any patent
+rights granted to you under this License for this implementation of Go
+shall terminate as of the date such litigation is filed.

package/templates/_shared/LICENSES/TEMPLATE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 synopkgland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/_shared/notice-overrides/index.json

@@ -0,0 +1,14 @@
+{
+  "@better-auth/utils@0.4.2": {
+    "integrity": "sha512-AUxrvu+HaaODsUyzDxFgwd/8RZ1yZaYo42LXKSrU2oGgR38pS1ij8nqQKNgtTWoYGpNevNXtCfgTy6loHveW9A==",
+    "file": "utils-0.4.2-LICENSE",
+    "source": "https://github.com/better-auth/utils/blob/ef522888b7b2ff77ca13f0afb476dfae8f297862/LICENSE",
+    "provenance": "Release manifests declare MIT but omit license text; retained upstream project license added in commit ef522888b7b2ff77ca13f0afb476dfae8f297862"
+  },
+  "@better-auth/utils@0.5.0": {
+    "integrity": "sha512-BL8W4EfIZFwlu0r54m3v1ztjDhu6dDe/amLTm0xybmbZaNgYUqhD3SjpAsnq0q8YD6/ki4iwIgxJNLP/N3TxiA==",
+    "file": "utils-0.5.0-LICENSE",
+    "source": "https://github.com/better-auth/utils/blob/ef522888b7b2ff77ca13f0afb476dfae8f297862/LICENSE",
+    "provenance": "Release manifests declare MIT but omit license text; retained upstream project license added in commit ef522888b7b2ff77ca13f0afb476dfae8f297862"
+  }
+}

package/templates/_shared/notice-overrides/utils-0.4.2-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 - present, Bereket Engida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/_shared/notice-overrides/utils-0.5.0-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 - present, Bereket Engida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/_shared/third-party-notices.mjs

@@ -0,0 +1,51 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Conservative inventory of every locked production dependency, including
+// dependencies tree-shaken from the bundle. Build tools marked dev are omitted.
+// Read actual upstream license/notice files, never synthesize license text from
+// SPDX metadata. npm ci must have installed the exact lock before this runs.
+export function writeThirdPartyNotices(root, output, { ui = false } = {}) {
+  const lock = JSON.parse(readFileSync(join(root, 'package-lock.json'), 'utf8'));
+  if (lock.lockfileVersion < 2 || !lock.packages) throw new Error('Notice generation requires a v2/v3 npm lockfile');
+  const inventory = [];
+  const sections = [];
+  let uiFiles;
+  for (const [path, entry] of Object.entries(lock.packages).sort(([a], [b]) => a.localeCompare(b, 'en'))) {
+    if (!path || entry.dev) continue;
+    if (!/^node_modules\//.test(path) || path.split('/').includes('..') || entry.link) throw new Error(`Unsupported notice package path: ${path}`);
+    const dir = join(root, path);
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    if (pkg.version !== entry.version) throw new Error(`Notice version mismatch: ${path}; run npm ci`);
+    const files = readdirSync(dir, { withFileTypes: true })
+      .filter(f => f.isFile() && /^(licen[sc]e|copying|notice|copyright)([.-]|$)/i.test(f.name))
+      .map(f => f.name).sort();
+    const texts = files.map(file => ({ file, text: readFileSync(join(dir, file), 'utf8') }));
+    let source, provenance;
+    if (!files.some(f => /^(licen[sc]e|copying)([.-]|$)/i.test(f))) {
+      const index = new URL('./notice-overrides/index.json', import.meta.url);
+      const overrides = existsSync(index) ? JSON.parse(readFileSync(index, 'utf8')) : {};
+      const override = overrides[`${pkg.name}@${pkg.version}`];
+      if (!override || !entry.integrity || override.integrity !== entry.integrity) throw new Error(`Missing upstream license text: ${pkg.name}@${pkg.version}`);
+      source = override.source;
+      provenance = override.provenance;
+      texts.push({file: 'LICENSE (pinned upstream source)', text: readFileSync(new URL(`./notice-overrides/${override.file}`, import.meta.url), 'utf8')});
+      files.push(override.file);
+    }
+    // UI ships its own aggregate for fonts, icons and dependencies/assets.
+    if (pkg.name === '@synopackageland/ui') {
+      uiFiles = {
+        'UI-LICENSE': readFileSync(join(dir, 'LICENSE'), 'utf8'),
+        'UI-THIRD_PARTY.md': readFileSync(join(dir, 'LICENSES/THIRD_PARTY.md'), 'utf8'),
+      };
+    }
+    inventory.push({ name: pkg.name, version: pkg.version, license: pkg.license ?? entry.license ?? 'unknown', integrity: entry.integrity, path, files, ...(source ? {source, provenance} : {}) });
+    sections.push(`\n===== ${pkg.name}@${pkg.version} (${pkg.license ?? entry.license ?? 'unknown'}) =====\n` + (source ? `Source: ${source}\n${provenance}\n` : '') + texts.map(({ file, text }) => `\n--- ${file} ---\n${text}\n`).join(''));
+  }
+  if (ui && !uiFiles) throw new Error('UI dependency is missing from the locked production inventory');
+  rmSync(output, { recursive: true, force: true });
+  mkdirSync(output, { recursive: true });
+  writeFileSync(join(output, 'THIRD_PARTY_NOTICES.txt'), 'Locked production dependency notices (conservative superset of bundled code).\n' + sections.join(''));
+  writeFileSync(join(output, 'inventory.json'), JSON.stringify(inventory, null, 2) + '\n');
+  for (const [name, text] of Object.entries(uiFiles ?? {})) writeFileSync(join(output, name), text);
+}

package/templates/binary/synology-app.yaml

@@ -4,4 +4,4 @@ version: 0.1.0
 displayname: Binary App
 description: A minimal Syno Package Land app that runs one prebuilt binary.
 maintainer: Syno Package Land
-os_min_ver: "7.2-60000"
+os_min_ver: "7.1-42661"

package/templates/compose-import/compose.yaml

@@ -1,6 +1,6 @@
 services:
   app:
-    image: hello-world:latest
+    image: hello-world:latest@sha256:5e23090353324d887c48ad5e5c56d294eab81588df9605b07d1afe895f9cc8f8
     volumes:
       - "${MEDIA_SHARE}:/media"
       - "${BACKUP_SHARE}:/backup"

package/templates/compose-import/synology-app.yaml

@@ -4,7 +4,7 @@ version: 0.1.0
 displayname: Compose Import
 description: Start from an existing Compose file and select two Shared Folders at install time.
 maintainer: Syno Package Land
-os_min_ver: "7.2-69057"
+os_min_ver: "7.2.1-69057"
 
 install:
   MEDIA_SHARE:

package/templates/hello-files/compose.yaml

@@ -1,6 +1,6 @@
 services:
   worker:
-    image: alpine:3.20
+    image: alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc
     command: ["sleep", "infinity"]
     volumes:
       # intentionally outside the zero-config docker-project resource-worker path.

package/templates/hello-files/synology-app.yaml

@@ -4,7 +4,7 @@ version: 0.1.0
 displayname: Hello Files
 description: A minimal headless app with a Shared Folder mount.
 maintainer: Syno Package Land
-os_min_ver: "7.2-69057"
+os_min_ver: "7.2.1-69057"
 
 install:
   MEDIA_SHARE:

package/templates/hello-web/compose.yaml

@@ -1,6 +1,6 @@
 services:
   web:
-    image: busybox:1.36
+    image: busybox:1.36@sha256:73aaf090f3d85aa34ee199857f03fa3a95c8ede2ffd4cc2cdb5b94e566b11662
     # DSM worker constraints to preserve when changing this service:
     # 1) command/entrypoint arrays must not contain bare numeric elements
     #    (such as "18333"). DSM's docker-project worker drops the quotes on a
@@ -15,7 +15,10 @@ services:
     # injects an arbitrary package UID/GID, and the nginx entrypoint needs
     # root during startup, so it exits immediately under that identity.
     command: ["sh","-c","httpd -f -p 18333 -h /usr/share/nginx/html"]
+    # Bound to loopback on purpose: the DSM-authenticated gateway generated by
+    # `synopkgland build-spk` is the only way in. A port on every interface would
+    # bypass DSM sign-in, and `synopkgland validate` rejects it.
     ports:
-      - "18333:18333"
+      - "127.0.0.1:18333:18333"
     volumes:
       - "./html:/usr/share/nginx/html:ro"

package/templates/hello-web/synology-app.yaml

@@ -4,10 +4,13 @@ version: 0.1.0
 displayname: Hello Web
 description: A minimal Syno Package Land web app template.
 maintainer: Syno Package Land
-os_min_ver: "7.2-69057"
+os_min_ver: "7.2.1-69057"
 adminprotocol: http
 adminport: 18333
 adminurl: /
 integration:
   web:
     launch: dsm-window
+    # Who may open the app: dsm-users (any signed-in DSM user), dsm-admins,
+    # dsm-groups (with groups: [...]) or public (no DSM sign-in).
+    access: dsm-users

package/templates/hello-web-page/compose.yaml

@@ -1,6 +1,6 @@
 services:
   web:
-    image: busybox:1.36
+    image: busybox:1.36@sha256:73aaf090f3d85aa34ee199857f03fa3a95c8ede2ffd4cc2cdb5b94e566b11662
     # DSM worker constraints to preserve when changing this service:
     # 1) command/entrypoint arrays must not contain bare numeric elements
     #    (such as "18333"). DSM's docker-project worker drops the quotes on a
@@ -15,7 +15,10 @@ services:
     # injects an arbitrary package UID/GID, and the nginx entrypoint needs
     # root during startup, so it exits immediately under that identity.
     command: ["sh","-c","httpd -f -p 18333 -h /usr/share/nginx/html"]
+    # Bound to loopback on purpose: the DSM-authenticated gateway generated by
+    # `synopkgland build-spk` is the only way in. A port on every interface would
+    # bypass DSM sign-in, and `synopkgland validate` rejects it.
     ports:
-      - "18333:18333"
+      - "127.0.0.1:18333:18333"
     volumes:
       - "./html:/usr/share/nginx/html:ro"

package/templates/hello-web-page/synology-app.yaml

@@ -4,10 +4,13 @@ version: 0.1.0
 displayname: Hello Web Page
 description: A Syno Package Land web app template that opens in a new browser page.
 maintainer: Syno Package Land
-os_min_ver: "7.2-69057"
+os_min_ver: "7.2.1-69057"
 adminprotocol: http
 adminport: 18333
 adminurl: /
 integration:
   web:
     launch: new-page
+    # Who may open the app: dsm-users (any signed-in DSM user), dsm-admins,
+    # dsm-groups (with groups: [...]) or public (no DSM sign-in).
+    access: dsm-users

package/templates/native-go/README.md

@@ -135,9 +135,75 @@ Known limits:
 `ui/app.js` must register `window.DsmPackageApps[<package>].mount(root, ctx)`
 (the template shows how, using `document.currentScript.dataset.package`).
 `ctx.call(method, params)` is the only transport. `ctx.reopen(fn)` runs `fn`
-whenever DSM shows the window again. Scope your CSS under your own root class:
+whenever DSM shows the window again and returns an idempotent unsubscribe function. Scope your CSS under your own root class:
 every DSM app shares one page.
 
+Plain JS and Vue receive the same `ctx.host` adapter. `ctx.host.platform()`
+returns a fresh frozen snapshot: `web`, `host` (`dsm`, `standalone-web` or
+`unavailable`), `dsmStandalone`, `dsmLanguage`, `appLocale`, `systemVersion`,
+`fullVersion`, and `theme`. Unknown fields are `null`; `theme` stays unknown.
+DSM launch mode is separate from plain-web fallback, and `appLocale` is the
+app's catalog locale, which may differ from DSM's UI language code.
+
+```js
+const platform = ctx.host.platform();
+const result = ctx.host.setTitle('My notes');
+if (result.status !== 'ok') showTitleStatus(result.status);
+```
+
+`setTitle` enables DSM HTML encoding or assigns standalone `document.title`.
+It returns `{status: 'ok', target: 'dsm-window' | 'document'}` on synchronous
+completion, or `unsupported`, `unavailable`, `invalid-input`, `failed` statuses.
+A missing DSM method is unsupported; it never changes the DSM desktop's title.
+Destroy disposes the adapter and clears reopen handlers; retained adapters
+return unavailable. Navigation exposes activateWindow/requestClose/openApp/openURL;
+requests do not acknowledge completion. `ctx.host.subscribe('window-resize', fn)`
+returns `{status: 'subscribed', dispose}` only for a verified DSM window with on/un.
+The callback receives no native arguments. Remove your subscriptions on unmount;
+wrapper destroy also cleans them. `host-theme-change` and `host-language-change`
+return unsupported: no third-party host event is proven. These observations do
+not authorize work.
+
+`ctx.host.openFileManager('/example-share/docs')` requests File Station folder
+navigation; `revealFile('/home/report.txt')` requests a file highlight. Both require
+a registered, enabled and launchable File Station and report requested plus action,
+not location completion or ACL success. Use canonical virtual share paths only;
+OS `/volumeN/...`, traversal, repeated/trailing slash, controls and backslash are
+invalid. No path conversion or grant is performed. `openFile`, `showFileDetails`
+and `openAppSetting` return unsupported; private preview/details/settings flows
+have no proven generic contract.
+
+File reveal adds a best-effort correction using File Station 1.4.x private
+structures. Required APIs are feature-detected; absent/throwing APIs silently
+cancel and release timers/listeners. One AppLaunch callback binds one receiver;
+only its model may be selected once. Interaction, navigation away from the reached
+parent, close/destroy, disposal and new requests cancel the correction. The named
+5000 ms total budget, 100 ms checks and 300 ms quiet interval have no device latency
+proof. `requested` still does not mean `selected`; actual effectiveness on DSM 7.4 /
+File Station 1.4.4 awaits a rebuilt-SPK device matrix. No second launch or broadcast
+setter is used, and later reloads may still clear selection.
+
+For an independent browser shell, use the SPK's generated `ui/host-0001.js`
+(the number follows the manifest build). It has no Ext or npm runtime dependency:
+
+```html
+<script src="./host-0001.js"></script>
+```
+
+```js
+// shellContext supplies your app's own auth/transport and other context members.
+const ctx = {...shellContext, host: window.DsmPackageHosts.__PACKAGE__({locale: 'en'})};
+const app = window.DsmPackageApps.__PACKAGE__.mount(root, ctx);
+// When your shell unmounts:
+ctx.host.dispose();
+app.unmount();
+```
+
+Serve the generated script with your shell (or reference its same-origin DSM
+static path). `ctx.host` does not create a standalone backend, DSM session,
+cross-origin iframe bridge, or implementations of `ctx.call/t/root/reopen`.
+Standalone title affects the document shared by that shell's mounts.
+
 To build the UI with Vite, Vue or React, point `ui` at the build output and
 give the build command as an argv list (no shell):
 
@@ -150,7 +216,7 @@ ui:
 ```
 
 The build must emit `app.js` (one script that registers `mount`) and
-`app.css`. The public `@synopackageland/ui@0.4.0` package on
+`app.css`. The public `@synopackageland/ui@0.5.7` package on
 `https://registry.npmjs.org` gives Vue components with DSM 7 styling;
 import its `themes/dsm7-embedded.css` for use inside a DSM window.
 
@@ -213,6 +279,51 @@ 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.
 
+### What an upgrade keeps
+
+An upgrade replaces the program files and keeps the data. DSM preserves `var`
+(`@appdata`), `home` (`@apphome`) and `etc` (`@appconf`) across an upgrade and
+removes `tmp` (`@apptemp`) and `target` (`@appstore`). Keep everything you need
+to keep under `var`, `home` or `etc`.
+
+### Schema migrations
+
+`backend/internal/datamigrate` applies ordered, idempotent schema migrations and
+records the result in `<var>/data-version`. `backend/cmd/app` runs `app.Migrate`
+on every start; the recorded version makes that a cheap no-op.
+
+- Versions start at 1 and never change meaning. The template ships one empty
+example in `backend/internal/app/migrations.go`; replace it with your steps.
+- Every step must be idempotent: a crash between `Apply` and the version record,
+or two CGI requests racing on the first start after an upgrade, can run one step
+twice.
+- A step that fails stops the run with the previous version still recorded, and
+the next start resumes from there. The helper never deletes or rewrites data
+itself, so a failed migration leaves your old data in place.
+- `datamigrate.Context.OldPkgVer` is the version being upgraded from:
+`SYNOPKG_OLD_PKGVER` when your environment sets it, otherwise the version the last
+successful run recorded. `NewPkgVer` is the version running now.
+
+Uninstalling keeps your data: DSM leaves `@appdata` and `@apphome` on the volume,
+and reinstalling the same package ID picks them up again. The install wizard is a
+dynamic `WIZARD_UIFILES/install_uifile.sh` that checks — read-only — whether
+`@appdata/<package>` already exists and, if it does, tells the administrator the
+install reuses the old data and how to start clean.
+
+The generated SPK ships
+an uninstall wizard (English, plus eight other languages) with one box, **Also
+delete the app data listed above** (`pkgwizard_remove_additional`), unchecked by
+default. Ticked, `postuninst` empties `@appdata/<package>` and `@apphome/<package>`
+and nothing else: not `@appconf`, Shared Folders, the package account or other
+packages. An upgrade never deletes anything. Do not write your own `postuninst`;
+`synopkgland inspect --spk` flags a deleting script that lacks the upgrade guard
+or deletes outside the package's own folders.
+
+A package with a root integration (the helper) also warns in its uninstall
+wizard: disable the integration in the App first. While it stays enabled,
+`preuninst` refuses the uninstall and writes the reason to
+`SYNOPKG_TEMP_LOGFILE`, which Package Center shows.
+
 ## Root access
 
 By default (`privilege: none`) nothing in this package ever runs as root, and
@@ -239,7 +350,8 @@ How it works, with no keys or signing involved:
    DSM language. A DSM administrator clicks **Authorize** and confirms with
    their DSM password in DSM's own dialog. DSM then creates one **disabled**
    root task in Task Scheduler, named `<package> root: <name>`. The
-   confirmation is used for that one task and never stored.
+   DSM 7.2+ uses its one-use password token for that task and never stores it.
+   DSM 7.1 uses the client-side confirmation described below.
 3. **Run** checks that the task is still exactly the approved text, runs it
    with the administrator's session and shows its result. The task writes
    only to `/run/synopkgland-<package>/<name>.out`, which root owns and your
@@ -252,6 +364,39 @@ How it works, with no keys or signing involved:
    password. Remove it before uninstalling the package, because DSM keeps
    Task Scheduler tasks after an uninstall.
 
+Root templates keep a minimum of **DSM 7.1-42661**. Init, validation and build
+reject a root-package minimum below that version. DSM 7.0 has not been verified.
+The window probes TaskScheduler `list v3` once per access instance; only DSM
+error 103 selects the legacy API matrix. Permission, session and network errors
+do not trigger a fallback, and create/run requests are never automatically
+resent with another API version.
+
+| Operation | DSM 7.1 | DSM 7.2+ |
+| --- | --- | --- |
+| List / detail | `list v2` (offset/limit) / `get v3` | `list v3` (start/limit) / `get v4` |
+| Create | `TaskScheduler.create v3` | `TaskScheduler.Root.create v4` + `SynoConfirmPWToken` |
+| Run / delete | `run v2` / `delete v2` | `run v2` / `delete v2` |
+| Completion | `view v1` | `get_history_status_list v1` |
+
+**DSM 7.1 security difference:** DSM's PasswordConfirmDialog is still required
+in the window, but root-task creation has **no server-side password token**.
+Any authenticated administrator session can call `create v3` to create root
+tasks without this client dialog. The client confirmation records the user's
+intent; it does not provide the server-enforced fresh password proof of the
+7.2+ Root API. Both paths verify task name, root owner/real owner, disabled
+script type and the exact approved action text before run or removal.
+
+The legacy path saves the existing history before run and requires one new,
+completed record with a valid `stop_time`, integer `exit_code: 0` and
+`exit_type: normal`. It checks task identity again before returning output.
+An accepted run request or old output never proves completion. Calls and polls
+share a 30-second deadline (at most 60 polls, 500 ms apart); a timeout does not
+cancel a task that DSM already started. Concurrent calls in one window share
+one run. Existing running tasks, malformed or ambiguous history, and incomplete
+scheduler lists are refused. List/history snapshots are limited to 500 entries.
+Second-resolution history cannot identify same-second reruns reliably; those
+runs may time out rather than reuse an old success record.
+
 Non-administrators see DSM's "Only administrator accounts can perform this
 operation." and nothing else. HTTP requests can never choose what runs as
 root: the only root code is the fixed text an administrator approved. Your app
@@ -264,5 +409,5 @@ drive the same flow from its own UI.
 | --- | --- |
 | Build hosts | macOS, Linux (any OS with Go and Node) |
 | Target CPUs | x86_64 and aarch64 DSM models (one SPK each) |
-| DSM | 7.2 or later declared (`os_min_ver`). Installed and tested on DSM 7.4 (x86_64). aarch64 SPKs are built the same way but have not been run on a NAS. |
+| DSM | 7.1 or later declared (`os_min_ver`, change it with `init --min-dsm` or `build-spk --min-dsm`). Installed and tested on DSM 7.4 (x86_64). aarch64 SPKs are built the same way but have not been run on a NAS. |
 | Not supported | 32-bit ARM, DSM 6, running anything as root without an administrator's approval |