@synopackageland/templates 0.9.5 → 0.9.6

package/templates/native-go/backend/internal/app/uninstall_test.go

@@ -0,0 +1,33 @@
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestUninstallDeletesTheJobSpoolOnlyWhenAsked(t *testing.T) {
+	dir := t.TempDir()
+	spool := filepath.Join(dir, "background")
+	if err := os.MkdirAll(filepath.Join(spool, "inputs"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := Uninstall(dir, false); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(spool); err != nil {
+		t.Fatalf("kept state is gone: %v", err)
+	}
+	if err := Uninstall(dir, true); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(spool); !os.IsNotExist(err) {
+		t.Fatalf("state not deleted: %v", err)
+	}
+	if _, err := os.Stat(dir); err != nil {
+		t.Fatalf("package data must stay: %v", err)
+	}
+	if err := Uninstall(dir, true); err != nil {
+		t.Fatalf("nothing left to delete: %v", err)
+	}
+}

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

@@ -69,3 +69,21 @@ i18n:
 
 # Optional SDK capabilities; delegate/rootOps share administrator-approved executor setup.
 capabilities: {}
+
+# Optional uninstall hook. DSM runs `exec args` as the package account on a
+# real uninstall (not an upgrade), before the executor is removed, with
+# SYNOPKGLAND_DELETE_STATE=0|1 and SYNOPKGLAND_REMOVE_DATA=0|1 from the wizard.
+# A failure or timeout is logged (syslog tag synopkgland-uninstall, output in
+# var/uninstall-hook.log) and never blocks the uninstall. The backend's
+# `uninstall` mode deletes the background job spool when the admin ticks
+# "delete state"; add uninstall.state.jobs to i18n/messages in every language.
+# uninstall:
+#   purge:
+#     exec: ui/cgi/api.cgi
+#     args: [uninstall]
+#     timeout: 60            # seconds, 2..120
+#     # root: purge          # rootOps only: root/purge.sh runs as root at
+#     #                      # uninstall, and only while its approval stands
+#   state:
+#     items:
+#       - key: jobs          # i18n key uninstall.state.jobs

package/templates/native-go-delegate/backend/cmd/background-worker/main.go

@@ -37,7 +37,7 @@ func main() {
 	defer stop()
 	log.Printf("started as uid %s", strconv.Itoa(info.UID))
 	dataDir := "/var/packages/" + packageID + "/var"
-	service := &delegate.Service{Client: delegate.Local(packageID), Store: background.NewStore(dataDir + "/background"), StagingDir: dataDir + "/executor-staging"}
+	service := &delegate.Service{Client: delegate.Local(packageID), Store: background.NewStore(dataDir + "/background"), StagingDir: dataDir + "/executor-staging", Work: app.HashWork}
 	settings, err := app.ParseDelegateConfig(app.Config{DelegateScope: delegateScope, DelegateOperationsJSON: delegateOperationsJSON, DelegateDestinationsJSON: delegateDestinationsJSON, DelegateLifetime: delegateLifetime})
 	if err != nil {
 		log.Fatal(err)

package/templates/native-go-jobs/backend/internal/app/background_routes_test.go

@@ -35,11 +35,15 @@ func init() {
 	sampleParams["bg.jobs.list"] = `{}`
 	sampleParams["bg.jobs.get"] = id
 	sampleParams["bg.jobs.cancel"] = id
+	sampleParams["bg.jobs.pause"] = id
+	sampleParams["bg.jobs.resume"] = id
 	sampleParams["bg.jobs.result"] = id
 	sampleOutcome["bg.browse"] = "session_required"
 	sampleOutcome["bg.jobs.submit"] = "session_required"
 	sampleOutcome["bg.jobs.get"] = "not_found"
 	sampleOutcome["bg.jobs.cancel"] = "not_found"
+	sampleOutcome["bg.jobs.pause"] = "not_found"
+	sampleOutcome["bg.jobs.resume"] = "not_found"
 	sampleOutcome["bg.jobs.result"] = "not_found"
 }
 

package/templates/native-go-jobs/frontend/test/background-page.test.ts

@@ -18,3 +18,24 @@ test('a jobs project mounts the background panel for the signed-in user',async()
   expect(root.querySelector('[data-page="background"]')).not.toBeNull()
  }finally{app.unmount();root.remove()}
 })
+test('the background panel pauses a running job and resumes a paused one',async()=>{
+ const submitter={user:'alice',uid:'1024'}
+ const jobs=[{id:'run',name:'a.bin',state:'running',submitter},{id:'held',name:'b.bin',state:'paused',pauseReason:'user',submitter}]
+ const call=vi.fn(async(method:string):Promise<unknown>=>{
+  if(method==='app.status')return {package:'Jobs',version:'1',user:'alice',admin:false}
+  if(method==='bg.status')return {owner:submitter,admin:false,revision:1,worker:{username:'pkg',alive:true},limits:{maxInputBytes:1024,maxQueued:8,maxOwnerPending:4,maxOwnerBytes:4096,jobTimeoutSeconds:60}}
+  if(method==='bg.jobs.list')return {jobs}
+  if(method==='bg.schedules.list')return {schedules:[]}
+  return {}
+ })
+ const root=document.createElement('div');document.body.append(root)
+ const app=mount(root,{locale:'en',call,reopen:()=>()=>{}} as unknown as Context)
+ const button=(id:string,label:string)=>Array.from(root.querySelectorAll(`[data-job-id="${id}"] button`)).find(b=>b.textContent===label) as HTMLButtonElement|undefined
+ try{
+  await settle()
+  button('run','Pause')!.click();await settle()
+  expect(call).toHaveBeenCalledWith('bg.jobs.pause',{id:'run'})
+  button('held','Resume')!.click();await settle()
+  expect(call).toHaveBeenCalledWith('bg.jobs.resume',{id:'held'})
+ }finally{app.unmount();root.remove()}
+})

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

@@ -7,7 +7,7 @@
       "name": "native-dsm-vue-app",
       "dependencies": {
         "@lucide/vue": "1.48.0",
-        "@synopackageland/sdk": "0.9.6",
+        "@synopackageland/sdk": "0.9.7",
         "@synopackageland/ui": "0.9.2",
         "vue": "3.5.43"
       },
@@ -1148,9 +1148,9 @@
       }
     },
     "node_modules/@synopackageland/sdk": {
-      "version": "0.9.6",
-      "resolved": "https://registry.npmjs.org/@synopackageland/sdk/-/sdk-0.9.6.tgz",
-      "integrity": "sha512-u0xoXjlNk1buGUDO/5KxQuS88zmwG/fIUlToLEIoyoEQfb3K0p/Jt8SVKg3+XuoWEiMZ3mzRkcTQ+AEnr3LKMw==",
+      "version": "0.9.7",
+      "resolved": "https://registry.npmjs.org/@synopackageland/sdk/-/sdk-0.9.7.tgz",
+      "integrity": "sha512-uU0GvgMXmTRX4UMrm6NUDQEiPdVze1Y6uE/mwmM8kqrhnLhe90kt0RrcSoEpSj9KMH+bXACz1Dw3OBRygiA2wg==",
       "license": "MIT",
       "peerDependencies": {
         "@lucide/vue": "^1.48.0",

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

@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "@lucide/vue": "1.48.0",
-    "@synopackageland/sdk": "0.9.6",
+    "@synopackageland/sdk": "0.9.7",
     "@synopackageland/ui": "0.9.2",
     "vue": "3.5.43"
   },

package/templates/native-rust/README.md

@@ -0,0 +1,381 @@
+# __DISPLAY_NAME__
+
+A native DSM package (`__PACKAGE__`): a Rust backend that DSM runs as a CGI,
+and a UI that opens in its own DSM window. It installs as an **unsigned** SPK,
+runs as its own DSM package account, needs no containers, and has no root by default.
+
+```text
+DSM main menu → DSM window (ui/app.js)
+                   │  ctx.call("greeting.get")  same-origin POST + DSM session
+                   ▼
+   /webman/3rdparty/__PACKAGE__/cgi/api.cgi   (backend/, runs as package user)
+      1. transport guards: POST, JSON, same origin, ≤ 1 MiB, bounded JSON complexity
+      2. one DSM authentication (unless the route is Public)
+      3. route policy: User or Admin  → refusal before any handler
+      4. your handler (backend/src/app)
+```
+
+## Quick start
+
+Needs Node.js with `synopkgland` installed, and Rust through rustup:
+`backend/rust-toolchain.toml` pins 1.97.1 with the three DSM targets, so the
+first `cargo` run installs them.
+
+```bash
+(cd backend && cargo test --locked)   # auth policy + route tests
+synopkgland build           # → dist/__PACKAGE__-0.1.0-0001-{x86_64,aarch64}.spk
+synopkgland inspect dist/__PACKAGE__-0.1.0-0001-x86_64.spk
+```
+
+Install: Package Center → Settings → General → Trust Level "Any publisher",
+then Manual Install with the SPK for your NAS's CPU. Open
+**__DISPLAY_NAME__** from the DSM main menu: it shows who you are signed in
+as, what the backend reports, and (for administrators) a form that stores a
+greeting in the package's data folder.
+
+## Capabilities and schema 2
+
+`dsm-package.yaml` requires `schema: 2` and `backend: {kind: rust, dir: backend, package: app}`.
+Declare `capabilities.files: session` for interactive File Station access,
+`capabilities.jobs: true` for persistent package-account jobs,
+`capabilities.identity: standalone` for independent DSM login, and
+`capabilities.rootOps: true` for administrator-approved fixed executor operations.
+`init --with files,jobs,root-ops` supports plain and Vue UI; `login` and
+`delegate` need the Vue UI. `daemon` cannot be combined with `jobs`, but it can
+be combined with an until-revoked `delegate`.
+
+```sh
+synopkgland add files jobs login
+synopkgland check --json
+synopkgland status --host my-nas --json
+```
+
+`add` writes SDK overlay files and updates capabilities. Your handlers/pages and
+application entry files remain app-owned. Differing existing overlay files and
+modified SDK placeholders cause `ADD_FILE_CONFLICT` with the conflicting paths;
+resolve them before retrying. Already-declared capabilities are a no-op.
+`check`, `build`, `inspect`, `deploy`, `status` emit one stdout object with
+`--json`; failures include `code`, `message`, `hint`.
+
+## Project layout
+
+| Path | What it is | Edit it? |
+| --- | --- | --- |
+| `dsm-package.yaml` | Package identity, version/build, arches, where backend and UI come from | Yes |
+| `ui/app.js`, `ui/app.css` | The app inside the DSM window | Yes — your UI |
+| `ui/…` | Any other assets; served from `/webman/3rdparty/__PACKAGE__/app/` | Yes |
+| `i18n/messages/<locale>.json` | UI text in nine languages | Yes |
+| `i18n/glossary.json` | DSM's own UI terms, and which messages must use them | Add terms |
+| `backend/src/app/` | Your API: routes and handlers | Yes — your backend |
+| `backend/permissions.json` | Who may call each of your methods | Yes |
+| `backend/src/bin/api.rs` | Wires your routes to the SDK server | Rarely |
+| `backend/Cargo.toml`, `backend/Cargo.lock` | Your crate; the `syno-pkg-land-sdk` dependency's `tag` pins the SDK, and the committed lock file pins everything else | SDK upgrades |
+| `backend/rust-toolchain.toml` | The Rust release and DSM targets the SPK is built with | Toolchain upgrades |
+| `dist/` | Built SPKs (ignored by git) | No |
+
+`build` generates everything else: `INFO`, `conf/privilege`
+(`run-as: package`), no-op lifecycle scripts, icons, the DSM window wrapper
+(`ui/config`, `ui/window-<build>.js`) and the CGI at `ui/cgi/api.cgi`.
+
+## Add an API operation
+
+Add a handler in `backend/src/app/routes.rs`. Every method defaults to
+DSM administrator membership, resolved by its native SDK. All access rules live in
+`backend/permissions.json`, including launcher access:
+
+```rust
+pub fn routes(cfg: Config) -> Vec<Route> {
+    let cfg = Arc::new(cfg);
+    vec![
+        cfg.handle("app.status", Config::status),
+        cfg.handle("greeting.get", Config::get_greeting),
+        cfg.handle("greeting.set", Config::set_greeting),
+        cfg.handle("notes.list", Config::list_notes),   // new: administrators by default
+        cfg.handle("notes.purge", Config::purge_notes), // new: administrators by default
+    ]
+}
+
+impl Config {
+    fn list_notes(&self, _: &Context, caller: &Caller, params: &[u8]) -> Result<Value, BoxError> {
+        #[derive(Default, Deserialize)]
+        #[serde(deny_unknown_fields)]
+        struct Params {
+            #[serde(default)]
+            limit: i64,
+        }
+        let _params: Params = decode_params(params)?;
+        Ok(json!({"owner": caller.user(), "notes": []}))
+    }
+}
+```
+
+Then add the method's valid params to `samples()` in `test_support.rs`; the
+test fails until you do, and once you do it proves the new route refuses
+callers without a session and ordinary users without touching
+the data folder.
+
+Call it from the UI with `ctx.call("notes.list", { limit: 20 })`. Errors
+reject with `{ code, message }`, for example `session_required`,
+`admin_required`, `bad_request` or `internal`.
+
+### Who can call what
+
+The shipped policy is:
+
+```json
+{"schema": 1, "default": "administrators", "methods": {}}
+```
+
+The default must remain `administrators`. An intentional exception belongs in
+`methods`, for example `"notes.list": "authenticated"`; `"public"` explicitly
+allows anonymous calls. Such exceptions also enable ordinary-user launcher
+access. The template ships no exceptions and sets DSM `allUsers` to `false`.
+
+| JSON rule | No session | Ordinary user | Administrators group member |
+| --- | --- | --- | --- |
+| absent or `administrators` | `session_required` | `admin_required` | runs |
+| explicit `authenticated` | `session_required` | runs | runs |
+| explicit `public` | runs | runs | runs |
+| unregistered method | `session_required` | `unknown_method` | `unknown_method` |
+
+Missing or invalid JSON, duplicate keys, unknown permissions and rules for
+unregistered methods fail closed. The CLI validates the file and binds its
+SHA-256 digest to the compiled CGI, which checks it at startup before migration.
+Changing policy requires rebuilding the SPK; request parameters cannot alter it.
+Register routes with `Route::handle`. Binary reads cannot be configured as anonymous.
+
+## The SDK
+
+Everything outside `backend/src/app`, `backend/permissions.json`
+and your UI comes from the SDK: the Rust crate `syno-pkg-land-sdk`
+(a git dependency pinned by `tag` in `backend/Cargo.toml`, the single source of the SDK version; `Cargo.lock` records the same tag) and, for the
+Vue UI, the npm package `@synopackageland/sdk` at the same version. Transport
+guards, DSM authentication, the administrator check, File Station, jobs,
+identity, portal, migrations and the executor protocol are documented in the SDK
+repository: <https://github.com/synopackageland/syno-pkg-land-sdk>.
+
+Upgrade the SDK by changing the dependency's `tag` and running `cargo update -p
+syno-pkg-land-sdk` (and changing `frontend/package.json`) to the new version; `synopkgland check` refuses mismatched versions.
+
+## Customize the UI
+
+`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 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):
+
+```yaml
+ui:
+  dir: web/dist
+  build:
+    cwd: web
+    command: [npm, run, build]
+```
+
+The build must emit `app.js` (one script that registers `mount`) and
+`app.css`. The installed `@synopackageland/ui` package gives Vue components with DSM 7 styling;
+import its `themes/dsm7-embedded.css` for use inside a DSM window.
+
+## Languages
+
+The UI ships in nine of DSM's languages: `en`, `zh-TW`,
+`zh-CN`, `ja`, `ko`, `de`, `fr`, `es` and `it`. DSM's other languages show
+English. The window follows DSM's own language setting (`_S("lang")`).
+
+- **Messages**: `i18n/messages/<locale>.json`, flat `"key": "text"`. Use
+  `ctx.t("greeting.setBy", { text, user })` in the UI; `{name}` is a
+  placeholder, and `ctx.t("files", { count: 3 })` picks `files.one` or
+  `files.other`. Missing keys fall back to English, then to the key itself.
+  `build` embeds the catalogs in the DSM window script, so there is no
+  extra request.
+- **Errors**: the backend returns a `code`; the UI shows
+  `error.<code>` from the catalogs and uses the backend's English text only for
+  codes it has no message for. Add `error.<code>` for every code you return.
+- **Glossary**: `i18n/glossary.json` records DSM's own words in all nine
+  languages, each with its source (`section/key` in DSM 7.4's
+  `/usr/syno/synoman/webman/texts/<lang>/strings`). A term's `keys` lists the
+  messages that must contain it; that is how "Save" uses DSM's own word in
+  every language, the same as the rest of DSM. Product names in `untranslated`
+  stay in English everywhere.
+- **Package Center text**: `i18n.info` in `dsm-package.yaml` writes INFO
+  `displayname_<lang>` / `description_<lang>` (for example `description_cht`).
+
+`synopkgland check` and `build` refuse a language file with missing or
+extra keys, a translation that drops a `{placeholder}`, an unsupported
+language, or a listed message that drifts from the glossary.
+
+To add a message: add the key to `en.json` and to the other eight files. To
+use a DSM term, copy its `text` from the glossary and add your key to the
+term's `keys`. A Vue or React UI can keep its own i18n library; `ctx.t` and
+`ctx.locale` are there if you want them.
+
+The Vue shell (`--ui vue`) keeps the app's own text in `frontend/src/i18n/<locale>.json`,
+in the same nine languages; SDK components (sign-in, files, background jobs) ship
+their own catalogs. Add new text to all nine files rather than writing it into a
+`.vue` file.
+
+## Package an existing binary
+
+Keep the Rust backend and call your tool from a handler (recommended: auth
+stays central), or replace the CGI with your own executable:
+
+```yaml
+arches: [x86_64]
+backend:
+  kind: binary
+  files:
+    x86_64: prebuilt/api-x86_64
+```
+
+The file must be a regular file in the project, a 64-bit Linux ELF for that
+arch, and statically linked (DSM models ship different libc versions). It is
+installed as `ui/cgi/api.cgi` (mode 0755) and runs as the package account.
+It then owns everything the SDK server does for you: bounded reads,
+POST-only JSON, same-origin checks, authentication before any work, and a
+refusal for unknown methods.
+
+## DSM Application Portal link
+
+Only an App with the root executor (`rootOps` or `delegate`) can declare a
+portal; `synopkgland add root-ops portal` declares both. Uninstall then
+removes the App's Application Privileges rules and reloads nginx once DSM has
+removed the alias, so it stops answering. `synopkgland add portal` adds
+`portal: {}` to dsm-package.yaml so
+`https://<nas>/<alias>/` opens this app right after DSM sign-in. The install
+wizard proposes the alias (the package name in lowercase by default); an
+administrator turns it on from the app's portal panel or Control Panel >
+Login Portal > Applications. Ordinary users then see the link; until then
+they see "ask an administrator". DSM owns the setting: the backend's
+`portal.status` only reads it, and nothing in the package may write it. See
+`synopkgland skill show portal`.
+
+A portal needs DSM 7.3.2-86009 or later, so `add portal` raises a lower
+`os_min_ver` and build refuses one below it. DSM 7.1.1 rejects an unsigned
+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:`.
+
+## 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.
+
+### 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
+
+The SDK's `datamigrate` module applies ordered, idempotent schema migrations and
+records the result in `<var>/data-version`. `backend/src/bin/api.rs` 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/src/app/migrations.rs`; replace it with your steps.
+- Every step must be idempotent: a crash between the step 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::old_pkg_ver` is the version being upgraded from:
+`SYNOPKG_OLD_PKGVER` when your environment sets it, otherwise the version the last
+successful run recorded. `new_pkg_ver` 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>`, `@apphome/<package>`
+and `@appconf/<package>` and nothing else: not Shared Folders, the package
+account or other packages. An upgrade never deletes anything. Do not write your own `postuninst`;
+`synopkgland inspect` flags a deleting script that lacks the upgrade guard
+or deletes outside the package's own folders.
+
+## Support matrix
+
+| | Status |
+| --- | --- |
+| Build hosts | macOS, Linux (any OS with Rust and Node) |
+| Target CPUs | x86_64 and aarch64 DSM models (one SPK each). armv7 (DSM 7.2+ platforms `alpine`, `alpine4k`, `armada38x`, `monaco`) is opt-in: add it to `arches`; it covers the Rust CGI (plain or Vue UI), jobs, daemon, root-ops and delegate. armv7 jobs, daemon and executor (root-ops, delegate) are built and checked locally but have not been verified on a NAS |
+| DSM | 7.1 or later declared (`os_min_ver`, change it with `init --min-dsm` or `build --min-dsm`). Installed and tested on DSM 7.4 and 7.3.2 (x86_64). armv7 was installed and tested on DSM 7.1.1 (`alpine4k`, Linux 3.10, where the bridge runs from the package tmp fallback) with administrator, AppPriv and unauthenticated requests; `armada38x` and `monaco` have not been run on a NAS. No x86_64 Linux 3.10 model has been tested. aarch64 SPKs are built the same way but have not been run on a NAS. |
+| Not supported | armv7 platforms only DSM 7.0/7.1 ship (`armada370`, `armada375`, `armadaxp`, `comcerto2k`); DSM 6, running anything as root without an administrator's approval |

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

@@ -0,0 +1,125 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "app"
+version = "0.1.0"
+dependencies = [
+ "libc",
+ "serde",
+ "serde_json",
+ "syno-pkg-land-sdk",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "libc"
+version = "0.2.190"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.154"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "01016da373cd8f7ef12624f796309f5c31ba8d646dd08856c02cd741d823c622"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syno-pkg-land-sdk"
+version = "0.9.7"
+source = "git+https://github.com/synopackageland/syno-pkg-land-sdk?tag=v0.9.7#7f3a01ceb182caada349ee243c831efad3d3d93e"
+dependencies = [
+ "libc",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

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

@@ -0,0 +1,24 @@
+[package]
+name = "app"
+version = "0.1.0"
+edition = "2024"
+publish = false
+
+[[bin]]
+name = "api"
+path = "src/bin/api.rs"
+
+[[bin]]
+name = "background-worker"
+path = "src/bin/background-worker.rs"
+
+[dependencies]
+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-sdk = { git = "https://github.com/synopackageland/syno-pkg-land-sdk", tag = "v0.9.7" }
+
+[profile.release]
+# A handler panic becomes an "internal" reply (api::Server); abort would end the CGI instead.
+panic = "unwind"