@synopackageland/cli 0.6.1 → 0.7.1

package/dist/templates/_executor/tasks_dsm71_test.go

@@ -0,0 +1,114 @@
+package main
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// dsm71Scheduler answers like DSM 7.1.1-42962 (vt-62): TaskScheduler stops at
+// list v2 (offset/limit) and get v3. t-0234 measured the refusals: a version
+// above maxVersion 3 returns 104; a method absent at an existing version, 103.
+type dsm71Scheduler struct {
+	recordingScheduler
+	refusal string
+}
+
+func (s *dsm71Scheduler) Exec(ctx context.Context, path string, args []string) ([]byte, error) {
+	api, method, version := schedulerCall(args)
+	s.calls = append(s.calls, api+" "+method+" v"+version)
+	if api == "SYNO.Core.TaskScheduler" {
+		if method == "list" && version == "3" && s.refusal != "" {
+			return []byte(`{"success":false,"error":{"code":` + s.refusal + `}}`), nil
+		}
+		supported := map[string]string{"list": "2", "get": "3", "delete": "2", "run": "2"}
+		if supported[method] != version {
+			if version > "3" {
+				return []byte(`{"success":false,"error":{"code":104}}`), nil
+			}
+			return []byte(`{"success":false,"error":{"code":103}}`), nil
+		}
+		if method == "list" && (!contains(args, "offset=0") || !contains(args, "limit=500")) {
+			return []byte(`{"success":false,"error":{"code":101}}`), nil
+		}
+	}
+	return s.schedulerFixture.Exec(ctx, path, args)
+}
+
+func purgeWith(t *testing.T, cmd Command) {
+	t.Helper()
+	inventory := taskInventory{Package: "TestApp", PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: canonicalTaskDigest(t, "boot")}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: canonicalTaskDigest(t, "control")}}}
+	state := filepath.Join(t.TempDir(), "state")
+	socket := filepath.Join(t.TempDir(), "socket")
+	os.MkdirAll(filepath.Join(state, "runtime"), 0700)
+	os.MkdirAll(socket, 0700)
+	if err := purgeWithInventory(context.Background(), &liveDSM{Command: cmd}, "TestApp", inventory, state, filepath.Join(state, "runtime"), socket, func(string) {}); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestPurgeFindsAndDeletesBothTasksOnDSM71(t *testing.T) {
+	cmd := &dsm71Scheduler{}
+	purgeWith(t, cmd)
+	if strings.Join(cmd.deleted, ",") != "SYNO.Core.EventScheduler,SYNO.Core.TaskScheduler" {
+		t.Fatal("DSM 7.1 tasks left behind", cmd.deleted, cmd.calls)
+	}
+}
+
+func TestSchedulerReadFallsBackOnlyOnUnsupportedVersion(t *testing.T) {
+	for _, code := range []string{"105", "119", "102", "3121"} {
+		t.Run(code, func(t *testing.T) {
+			cmd := &dsm71Scheduler{refusal: code}
+			purgeWith(t, cmd)
+			for _, call := range cmd.calls {
+				if call == "SYNO.Core.TaskScheduler list v2" || call == "SYNO.Core.TaskScheduler get v3" {
+					t.Fatal("fell back after code", code, cmd.calls)
+				}
+			}
+			if contains(cmd.deleted, "SYNO.Core.TaskScheduler") {
+				t.Fatal("deleted without exact readback", cmd.deleted)
+			}
+		})
+	}
+}
+
+func TestModernSchedulerNeverUsesLegacyVersions(t *testing.T) {
+	cmd := &recordingScheduler{}
+	purgeWith(t, cmd)
+	for _, call := range cmd.calls {
+		if call == "SYNO.Core.TaskScheduler list v2" || call == "SYNO.Core.TaskScheduler get v3" {
+			t.Fatal("modern DSM used a legacy version", cmd.calls)
+		}
+	}
+	if len(cmd.deleted) != 2 {
+		t.Fatal(cmd.deleted)
+	}
+}
+
+type recordingScheduler struct {
+	schedulerFixture
+	calls []string
+}
+
+func (s *recordingScheduler) Exec(ctx context.Context, path string, args []string) ([]byte, error) {
+	api, method, version := schedulerCall(args)
+	s.calls = append(s.calls, api+" "+method+" v"+version)
+	return s.schedulerFixture.Exec(ctx, path, args)
+}
+
+func schedulerCall(args []string) (api, method, version string) {
+	for _, a := range args {
+		k, v, _ := strings.Cut(a, "=")
+		switch k {
+		case "api":
+			api = v
+		case "method":
+			method = v
+		case "version":
+			version = v
+		}
+	}
+	return
+}

package/dist/templates/_executor/tasks_review_test.go

@@ -35,7 +35,7 @@ func TestReviewSnapshotRejectsUnrelatedSameNamedRootTasks(t *testing.T) {
 func TestReviewPurgeRejectsUnrelatedSameNamedRootTasks(t *testing.T) {
 	script := "#!/bin/sh\n# synopkgland executor boot\n# " + strings.Repeat("a", 64) + strings.Repeat("b", 64) + "\necho unrelated-backup-task\n"
 	cmd := &schedulerFixture{script: script}
-	inv := taskInventory{Package: "TestApp", ExecutorDigest: strings.Repeat("a", 64), PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: hashBytes([]byte(script))}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: hashBytes([]byte(script))}}}
+	inv := taskInventory{Package: "TestApp", PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: hashBytes([]byte(script))}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: hashBytes([]byte(script))}}}
 	purgeTasks(context.Background(), &liveDSM{Command: cmd}, "TestApp", inv, func(string) {})
 	if len(cmd.deleted) != 0 {
 		t.Fatal("deleted unrelated tasks", cmd.deleted)

package/dist/templates/_executor/tasks_test.go

@@ -6,6 +6,7 @@ import (
 	"errors"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"synopkgland/executor/internal/taskscript"
 	"testing"
@@ -14,7 +15,9 @@ import (
 type schedulerFixture struct {
 	changed, foreignOwner, duplicate bool
 	script                           string
-	deleted                          []string
+	// deleteReply replaces the delete envelope, as DSM sends it.
+	deleteReply string
+	deleted     []string
 }
 
 func (s *schedulerFixture) Exec(_ context.Context, _ string, args []string) ([]byte, error) {
@@ -31,7 +34,7 @@ func (s *schedulerFixture) Exec(_ context.Context, _ string, args []string) ([]b
 	if s.foreignOwner {
 		owner = "other"
 	}
-	generated, _ := taskscript.Generate("TestApp", strings.Repeat("a", 64), strings.Repeat("b", 64))
+	generated, _ := taskscript.Generate("TestApp", strings.Repeat("b", 64))
 	script := generated[1].Script
 	if api == "SYNO.Core.EventScheduler" {
 		script = generated[0].Script
@@ -48,6 +51,9 @@ func (s *schedulerFixture) Exec(_ context.Context, _ string, args []string) ([]b
 		if api == "SYNO.Core.TaskScheduler" && !contains(args, `tasks=[{"id":7,"real_owner":"root"}]`) {
 			return nil, errors.New("wrong delete reference")
 		}
+		if s.deleteReply != "" {
+			return []byte(s.deleteReply), nil
+		}
 		data = map[string]any{}
 	} else if api == "SYNO.Core.EventScheduler" {
 		data = map[string]any{"task_name": "TestApp executor boot", "owner": map[string]string{"0": owner}, "operation": script, "operation_type": "script", "event": "bootup", "enable": true}
@@ -66,7 +72,7 @@ func TestPurgeDeletesOnlyExactOwnRootTasksAndProtectedState(t *testing.T) {
 	for _, mode := range []string{"exact", "script changed", "owner changed", "duplicate control", "foreign name"} {
 		t.Run(mode, func(t *testing.T) {
 			cmd := &schedulerFixture{changed: mode == "script changed", foreignOwner: mode == "owner changed", duplicate: mode == "duplicate control"}
-			inventory := taskInventory{Package: "TestApp", ExecutorDigest: strings.Repeat("a", 64), PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: canonicalTaskDigest(t, "boot")}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: canonicalTaskDigest(t, "control")}}}
+			inventory := taskInventory{Package: "TestApp", PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: canonicalTaskDigest(t, "boot")}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: canonicalTaskDigest(t, "control")}}}
 			if mode == "foreign name" {
 				inventory.Tasks[0].Name = "OtherApp executor boot"
 			}
@@ -101,7 +107,7 @@ func TestSnapshotRequiresBothExactSchedulerDefinitionsBeforeWritingInventory(t *
 			ed := strings.Repeat("a", 64)
 			pd := strings.Repeat("b", 64)
 			tasks := []map[string]string{}
-			generated, err := taskscript.Generate("TestApp", ed, pd)
+			generated, err := taskscript.Generate("TestApp", pd)
 			if err != nil {
 				t.Fatal(err)
 			}
@@ -152,7 +158,7 @@ func (s *snapshotFixture) Exec(ctx context.Context, path string, args []string)
 
 func canonicalTaskDigest(t *testing.T, kind string) string {
 	t.Helper()
-	tasks, err := taskscript.Generate("TestApp", strings.Repeat("a", 64), strings.Repeat("b", 64))
+	tasks, err := taskscript.Generate("TestApp", strings.Repeat("b", 64))
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -164,3 +170,54 @@ func canonicalTaskDigest(t *testing.T, kind string) string {
 	t.Fatal("task kind")
 	return ""
 }
+
+// t-0229: preuninst took 15-23 s; time each scheduler phase and the file
+// removal separately, naming the package, so a device log shows which waits.
+func TestPurgeLogsPhaseTimingWithPackageName(t *testing.T) {
+	cmd := &schedulerFixture{}
+	inventory := taskInventory{Package: "TestApp", PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: canonicalTaskDigest(t, "boot")}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: canonicalTaskDigest(t, "control")}}}
+	state := filepath.Join(t.TempDir(), "state")
+	socket := filepath.Join(t.TempDir(), "socket")
+	os.MkdirAll(filepath.Join(state, "runtime"), 0700)
+	os.MkdirAll(socket, 0700)
+	logs := []string{}
+	if err := purgeWithInventory(context.Background(), &liveDSM{Command: cmd}, "TestApp", inventory, state, filepath.Join(state, "runtime"), socket, func(s string) { logs = append(logs, s) }); err != nil {
+		t.Fatal(err)
+	}
+	task := regexp.MustCompile(`^task cleanup timing: package=TestApp kind=(boot|control) lookup_ms=\d+ delete_ms=\d+ verify_ms=\d+$`)
+	total := regexp.MustCompile(`^purge timing: package=TestApp tasks_ms=\d+ files_ms=\d+$`)
+	kinds := []string{}
+	for _, line := range logs {
+		if m := task.FindStringSubmatch(line); m != nil {
+			kinds = append(kinds, m[1])
+		}
+	}
+	if strings.Join(kinds, ",") != "boot,control" || len(logs) == 0 || !total.MatchString(logs[len(logs)-1]) {
+		t.Fatal(logs)
+	}
+}
+
+// t-0237: EventScheduler delete v1 and TaskScheduler delete v2 answer a success
+// without data; that is a confirmed delete, while a refusal stays unconfirmed.
+func TestPurgeConfirmsDatalessDeleteSuccess(t *testing.T) {
+	for reply, unconfirmed := range map[string]bool{
+		`{"success":true}`:                        false,
+		`{"httpd_restart":false,"success":true}`:  false,
+		`{"success":false,"error":{"code":4800}}`: true,
+		`{"success":true,"error":{"code":4800}}`:  true,
+	} {
+		cmd := &schedulerFixture{deleteReply: reply}
+		inventory := taskInventory{Package: "TestApp", PolicyDigest: strings.Repeat("b", 64), Tasks: []approvedTask{{Kind: "boot", Name: "TestApp executor boot", ScriptDigest: canonicalTaskDigest(t, "boot")}, {Kind: "control", Name: "TestApp executor control", ScriptDigest: canonicalTaskDigest(t, "control")}}}
+		logs := []string{}
+		purgeTasks(context.Background(), &liveDSM{Command: cmd}, "TestApp", inventory, func(s string) { logs = append(logs, s) })
+		found := 0
+		for _, line := range logs {
+			if strings.HasPrefix(line, "task cleanup unconfirmed: ") {
+				found++
+			}
+		}
+		if (found == 2) != unconfirmed || (found != 0 && found != 2) || len(cmd.deleted) != 2 {
+			t.Fatal(reply, logs)
+		}
+	}
+}

package/dist/templates/_executor/upgrade_watch_test.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"errors"
 	"net"
 	"os"
 	"path/filepath"
@@ -70,13 +71,20 @@ func TestUpgradeGapPreservesRuntimeAndResumesOnlyApprovedPins(t *testing.T) {
 						}
 						opened.Add(1)
 						return func() { listener.Close(); closed.Add(1) }, nil
-					}, func(ctx context.Context) bool { return samePackagePins(ctx, target, ed, pd) }, func() error {
+					}, func(ctx context.Context) bool {
+						// The production decision: only differing pins ask for approval.
+						pins := packagePins(ctx, target, info, func(os.FileInfo) bool { return true }, ed, pd)
+						return approvedPins(pins, func() error { return errors.New("no anchored upgrade here") }, func() error { return nil }, func(message string) {
+							if strings.Contains(message, "administrator approval") {
+								select {
+								case approval <- struct{}{}:
+								default:
+								}
+							}
+						})
+					}, func() error {
 						purged.Add(1)
 						return finishControl(state, filepath.Join(state, "runtime"), sockDir, true)
-					}, func(message string) {
-						if strings.Contains(message, "administrator approval") {
-							approval <- struct{}{}
-						}
 					})
 				}()
 				t.Cleanup(func() {

package/dist/templates/_executor/watch.go

@@ -32,6 +32,14 @@ func newLifecycleMonitor(pkg, packageDir, control string, log func(string)) *lif
 	return m
 }
 
+// A supervisor restart carries no new approval, so a stop already in the
+// mailbox stays in force.
+func newRevivedLifecycleMonitor(pkg, packageDir, control string, log func(string)) *lifecycleMonitor {
+	m := newLifecycleMonitor(pkg, packageDir, control, log)
+	m.initialStop = nil
+	return m
+}
+
 // DSM's var link is expected. Resolve its parent, then reject final symlinks,
 // FIFOs and oversized input. Linux openRegular pins all resolved components.
 func readLifecycleFile(path string, limit int) ([]byte, os.FileInfo, error) {

package/dist/templates/_executor/watch_test.go

@@ -209,7 +209,8 @@ func TestLifecycleWatchIgnoresInvalidControlAndResumesAfterOldStop(t *testing.T)
 	os.WriteFile(control, []byte("stop\n"), 0600)
 	var mu sync.Mutex
 	logs := 0
-	monitor := newLifecycleMonitor("TestApp", pkg, control, func(string) { mu.Lock(); logs++; mu.Unlock() })
+	observed := make(chan struct{}, 32)
+	monitor := newLifecycleMonitor("TestApp", pkg, control, func(string) { mu.Lock(); logs++; mu.Unlock(); observed <- struct{}{} })
 	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
 	defer cancel()
 	result := make(chan string, 1)
@@ -225,7 +226,13 @@ func TestLifecycleWatchIgnoresInvalidControlAndResumesAfterOldStop(t *testing.T)
 	checkRunning()
 	for _, value := range []string{"STOP", " purge", "purge\n\n", "purge;id", "wrong"} {
 		os.WriteFile(control, []byte(value), 0600)
-		checkRunning()
+		select {
+		case <-observed:
+		case got := <-result:
+			t.Fatalf("unexpected action %q", got)
+		case <-ctx.Done():
+			t.Fatal("invalid request not observed")
+		}
 	}
 	mu.Lock()
 	count := logs
@@ -268,3 +275,17 @@ func TestLifecycleMonitorReadsStartAfterStopAndKeepsCheckingPurge(t *testing.T)
 		}
 	}
 }
+
+// A supervisor restart is not a new administrator approval: the stop already in
+// the mailbox keeps the revived monitor paused.
+func TestRevivedMonitorHonorsStopAlreadyInMailbox(t *testing.T) {
+	pkg := t.TempDir()
+	os.WriteFile(filepath.Join(pkg, "INFO"), []byte("package=\"TestApp\"\n"), 0600)
+	control := filepath.Join(pkg, "control")
+	os.WriteFile(control, []byte("stop\n"), 0600)
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	if got := newRevivedLifecycleMonitor("TestApp", pkg, control, func(string) {}).watch(ctx, time.Millisecond); got != "stop" || ctx.Err() != nil {
+		t.Fatal("revived monitor ignored stop", got, ctx.Err())
+	}
+}

package/dist/templates/_executor/write_review_linux_test.go

@@ -11,15 +11,6 @@ import (
 	"time"
 )
 
-func TestReviewCopyChild(t *testing.T) {
-	if os.Getenv("P2_REVIEW_COPY_CHILD") != "1" {
-		t.Skip("child only")
-	}
-	if err := runWriteChild(os.Getenv("P2_REVIEW_CLEANUP_CHILD") == "1"); err != nil {
-		os.Exit(2)
-	}
-	os.Exit(0)
-}
 func TestReviewCanceledWriteDoesNotLeavePartialDestination(t *testing.T) {
 	if os.Geteuid() != 0 {
 		t.Skip("requires disposable local Linux root runner")
@@ -39,7 +30,7 @@ func TestReviewCanceledWriteDoesNotLeavePartialDestination(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if err = src.Truncate(1 << 40); err != nil {
+	if err = src.Truncate(8 << 30); err != nil {
 		src.Close()
 		t.Skip(err)
 	}
@@ -49,7 +40,7 @@ func TestReviewCanceledWriteDoesNotLeavePartialDestination(t *testing.T) {
 		t.Fatal(err)
 	}
 	launcher := filepath.Join(base, "child")
-	body := "#!/bin/sh\nexport P2_REVIEW_COPY_CHILD=1\n[ \"$1\" != cleanup-child ] || export P2_REVIEW_CLEANUP_CHILD=1\nexec " + strconv.Quote(binary) + " -test.run=^TestReviewCopyChild$\n"
+	body := "#!/bin/sh\nexport W3_MOVE_CHILD=\"$1\"\nexec " + strconv.Quote(binary) + " -test.run=^TestMoveChild$ 2>" + strconv.Quote(filepath.Join(base, "error")) + "\n"
 	os.WriteFile(launcher, []byte(body), 0700)
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
@@ -74,7 +65,8 @@ func TestReviewCanceledWriteDoesNotLeavePartialDestination(t *testing.T) {
 		}
 		select {
 		case err := <-done:
-			t.Fatalf("child ended before write: %v", err)
+			b, _ := os.ReadFile(filepath.Join(base, "error"))
+			t.Fatalf("child ended before write: %v %s", err, b)
 		case <-deadline:
 			t.Fatal("write did not start")
 		default:

package/dist/templates/_gateway/go.mod

@@ -1,3 +1,5 @@
 module synopkgland-gateway
 
 go 1.24
+
+toolchain go1.26.9

package/dist/templates/_shared/AGENTS.md

@@ -15,3 +15,132 @@ From the project root, run `synopkgland check --json`,
 `synopkgland build --json`, then `synopkgland inspect <spk> --json` on the emitted SPK.
 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.
+
+## Who may use the app (`entry`)
+
+Omit `entry` to keep legacy access. `entry: admin-only` admits DSM administrators
+only. `entry: app-privilege` also admits accounts that Control Panel >
+Application Privileges allows for `SYNO.SDS.<package>.Instance`; DSM's install
+default allows administrators only, so nobody else enters until an admin grants
+access. One CGI check covers every route; failures refuse; changes apply within
+30 seconds. Never re-implement AppPriv rules in the App.
+Mark routes ordinary users call `authenticated` in permissions.json, keep whole
+admin routes at the default, guard global settings inside shared routes with
+`api.RequireAdmin(caller)`, and hide admin controls with `ctx.user?.isAdmin`
+(UI only, never the authority). Example: users read the greeting; only admins
+call `greeting.set`.
+
+## DSM Application Portal (`portal`)
+
+`synopkgland add portal` (or `portal: {}` / `portal: {alias: my-app}` in
+dsm-package.yaml; Compose: `integration.web.portal` for a DSM-window app behind
+the auth gateway) registers `https://<nas>/<alias>/`, which opens the app after
+DSM sign-in. Read `synopkgland skill show portal` before changing it.
+The install wizard only proposes the alias; an administrator activates it from
+the app's portal panel (`ctx.portal`, DSM's own `SYNO.Core.AppPortal` in the
+admin's session) or Control Panel > Login Portal > Applications. Ordinary users
+get the link from the backend's read-only `portal.status`, else "ask an
+administrator". Never write `AppPortal.json` or `@appconf/<package>`, never add
+a backend route that sets the alias, and never relay QuickConnect responses or
+build QuickConnect links. A portal needs os_min_ver 7.3.2-86009 or later (DSM
+7.1.1 refuses it with error 320; 7.2 is untested) and `add portal` raises it;
+beyond that, support is detected (SYNO.API.Info), not version-gated.
+
+## Permanent destination integration
+
+`init --with delegate` / `add delegate` default to `operations: [files.moveFromStaging]`,
+`destinations: [save]`, `lifetime: until-revoked`, `scope: install-selected`. Existing legacy
+TTL declarations retain their 1–3600 second service / 30-day wire ceiling and
+64 MiB / 60-second URL example. Do not apply those limits to the new move API.
+Delegate can coexist with daemon; ordinary standalone jobs cannot. Preserve
+App business route floors. Binary/compose remain unsupported.
+
+Use File Station `/home[/...]`, never `/homes/<user>`. The SDK destination picker
+selection itself grants access after fresh DSM session/UID/write verification,
+without a second consent dialog. Ordinary and administrator subjects use their
+own nonzero UID/current groups, never root. An online App can create an in-scope
+grant using a valid session; there is no trusted external consent or notification.
+
+Use the default `createBackgroundSaveFacade(ctx)` / CapabilityPanels management
+page. `delegate.status` exposes verified `disabled` and manifest mode; missing
+protected evidence must not imply enabled. `delegate.operations.list` accepts
+only `{}`, uses the backend move mirrors, and returns the caller's username+UID
+operations only, including for admins. Mirrors are not completion receipts:
+query original `delegate.operations.get` and show Saved only for committed with
+a receipt. Cancel by the same reference; revoke by grant ID. Never resubmit
+uncertain/interrupted work. Admin disable is protected and revokes grants;
+enable/mailbox start does not resurrect them. Keep IDs, never session credentials.
+
+App-owned daemon completion and scheduled CSV export call configured Go
+`Service.MoveFromStaging` with `delegation_id`, stable `job_id`, private relative
+`staging`, `name`, `size`. No owner/UID selector. Bounds: 16 GiB/file, queued16,
+active1/package, 24-hour attempt, 5-second revalidation, 10 MiB operation records,
+50 MiB audit. Scope is a usage restriction, not hard subtree confinement.
+Local production-executor fixtures use fake DSM/peer/bulk writer; do not claim
+NAS ACL, actual writer UID, logout/reboot or full lifecycle acceptance from them.
+Gopeed product wiring remains a separate task.
+
+Admission recovery (per job): on `EXECUTOR_UNAVAILABLE`, `EXECUTOR_TIMEOUT`,
+`EXECUTOR_PROTOCOL`, `canceled`, `EXECUTOR_PAUSED`, `queue-full`,
+`STORAGE_ERROR`, `ADMISSION_PENDING`, `jobs_busy` or `jobs_unavailable` (the
+package journal was busy or failed transiently; a caller deadline or cancel
+spent waiting for it is `canceled`), call `MoveFromStaging` again later with
+the same exact params. It queries the original reference first and re-sends
+admission only when the executor does not know it and the pinned source is
+unchanged; executor tuple deduplication keeps one operation, so a lost reply or a
+racing caller never copies twice. At most 10 possibly-delivered sends, 2 s
+backoff doubling to 5 min; the worker sweep does the same. Terminal, do not
+retry: `APP_DENIED`, `DELEGATION_DENIED`, `operation-conflict`, `disabled`,
+`SCOPE_DENIED` and other executor refusals, `STAGING_CHANGED`,
+`ADMISSION_EXHAUSTED`, `spool_unsafe` and `journal_corrupt` (repair the package
+spool first), and `operation-not-found` for an accepted operation.
+Never change job/grant IDs, delete mirrors or call the socket directly to retry.
+
+Cancellation (per job): `CancelOperation` / `delegate.operations.cancel` with the
+original ref is idempotent; repeat it with the same ref after any retryable
+error or a lost reply. A reply `queued`→`canceled` is final at once. A copy in
+flight answers `copying` with code `CANCEL_REQUESTED`: the cancel is accepted and
+durable, not finished; poll `OperationStatus` on the same ref until terminal
+(repeating the cancel is harmless). `canceled` (`OPERATION_CANCELED`) guarantees the writer
+stopped, its part file is removed, nothing was published and staging is kept; it
+stays canceled across executor crash, package stop/start and logout. `committed`
+means publication won the race: the file stays (cancel never removes it) and only
+the app record may be dropped. `uncertain` means a publish attempt failed before
+the cancel; keep querying. A cancel of a ref the executor has not admitted yet
+(reserved/sent mirror) returns `canceled` and leaves a tombstone, so a late or
+recovered admission of that ref returns `canceled` and never copies; a producer
+cancel is also written to the mirror first, so `MoveFromStaging` and the worker
+sweep forward the cancel instead of admitting it.
+
+
+### Install-selected scope and the destination API
+
+- The DSM install wizard dynamically lists local shares (`SYNO.Core.Share list`
+  via `api_store`) and offers home. It saves only a package-owned pre-selection
+  in `var/delegate-install.json`; never trust that file for authority.
+- The existing administrator PasswordConfirm form displays this pre-selection
+  at first enable. `ctx.executor.authorize(password, selectedScope)` confirms it
+  through a pinned, exact-readback one-time root task. Settings changes use the
+  same form/password path; no App CGI route may set protected scope directly.
+- The executor trusts `/usr/local/etc/synopkgland/<pkg>/delegations/selected-scope.record`
+  only. Its scope/generation are runtime protected state; shipped policy pins
+  lock the selection mode and operations. Changes revoke old grants and cancel
+  pending writes. Change-away-and-back never revives an old grant.
+- Follow `selection` from verified `delegate.status` / `sdk.destination(key)`.
+  If the draft differs, display the difference and follow the protected value.
+  Home and fixed `shared:<name>` manifests stay compatible.
+- Frontend: `const sdk = createBackgroundSaveFacade(ctx); const current = await
+  sdk.destination('save')` returns typed `{key, selection, destination, status}`.
+  `selection` contains `{scope, root, generation}`; `destination` is this caller's
+  grant or null. Handle active/missing/reselection-required/needs-scope-confirmation/disabled.
+- Go: `Service.Destination(ctx, caller, request, key)` verifies the fresh DSM
+  session and username+UID. Capture its active grant ID into the App job. The
+  offline producer uses existing `Service.MoveFromStaging`; no user/UID selector,
+  cookie, token, or browser path cache. Executor revalidates at use/publication.
+- The generated Background saves page includes a working **Save example file**
+  (`sdk.exportExample({key, job_id})`, `delegate.example.export`). Go
+  `ExportExample` creates a private JSON file, calls `MoveFromStaging` once, and
+  repeats the original request on repeated IDs. Review `example.go` to
+  adapt a real producer; show Saved only from a protected committed receipt.
+- Wizard support is measured on vt-nas DSM 7.4 via a session-only SSH local
+  forward. This is not proof of other DSM releases or full writer/reboot behavior.

package/dist/templates/binary/dsm-package.yaml

@@ -6,7 +6,27 @@ build: 1
 displayname: __DISPLAY_NAME__
 description: A DSM package with a prebuilt binary CGI and DSM window UI.
 maintainer: Your Name
+# Optional INFO/website metadata. Omit fields you do not need.
+# metadata:
+#   contact_email: you@example.com
+#   support_email: support@example.com
+#   homepage: https://example.com
+#   source_url: https://github.com/you/your-app
+#   issues_url: https://github.com/you/your-app/issues
+#   license: MIT
+#   long_description:
+#     en: |-
+#       Explain what the app does and how to use it.
+#     zh-TW: Translated description.
+#   changelog:          # text, or per-language like long_description
+#     en: |-
+#       - Most important change first. Omit to use Release notes.
+#     zh-TW: |-
+#       - Translated changes.
+#   screenshots: [https://example.com/screenshot.png]
 os_min_ver: "7.1-42661"
+# One SPK per architecture. For armv7, add it here and a static 32-bit ARM file
+# under files (e.g. CGO_ENABLED=0 GOARCH=arm GOARM=7 go build).
 arches: [x86_64, aarch64]
 backend:
   kind: binary
@@ -14,6 +34,10 @@ backend:
     x86_64: prebuilt/api-x86_64
     aarch64: prebuilt/api-aarch64
 ui: {dir: ui}
+# UI languages: i18n/messages/<locale>.json for en, zh-TW, zh-CN, ja, ko, de,
+# fr, es and it (DSM's other languages fall back to English); ctx.t(key) reads them.
+i18n:
+  messages: i18n/messages
 # init compiles example/main.go for convenience. Replace prebuilt/api-* with
 # your application's static Linux ELF files; the CGI owns authentication.
 # daemon may optionally declare a separately packaged foreground service.

package/dist/templates/binary/i18n/messages/de.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "Ihr vorab kompiliertes CGI ist in dieser DSM-Anwendung enthalten.",
+  "app.title": "Binary App"
+}

package/dist/templates/binary/i18n/messages/en.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "Your prebuilt CGI is packaged in this DSM application.",
+  "app.title": "Binary App"
+}

package/dist/templates/binary/i18n/messages/es.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "Su CGI precompilado está empaquetado en esta aplicación de DSM.",
+  "app.title": "Binary App"
+}

package/dist/templates/binary/i18n/messages/fr.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "Votre CGI précompilé est intégré à cette application DSM.",
+  "app.title": "Binary App"
+}

package/dist/templates/binary/i18n/messages/it.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "Il CGI precompilato è incluso in questa applicazione DSM.",
+  "app.title": "Binary App"
+}

package/dist/templates/binary/i18n/messages/ja.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "事前にビルドした CGI がこの DSM アプリケーションにパッケージ化されています。",
+  "app.title": "Binary App"
+}

package/dist/templates/binary/i18n/messages/ko.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "미리 빌드한 CGI가 이 DSM 응용 프로그램에 패키징되어 있습니다.",
+  "app.title": "Binary App"
+}

package/dist/templates/binary/i18n/messages/zh-CN.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "预先构建的 CGI 已打包在此 DSM 应用程序中。",
+  "app.title": "Binary App"
+}

package/dist/templates/binary/i18n/messages/zh-TW.json

@@ -0,0 +1,4 @@
+{
+  "app.description": "預先建置的 CGI 已封裝在這個 DSM 應用程式中。",
+  "app.title": "Binary App"
+}

package/dist/templates/binary/ui/app.js

@@ -2,16 +2,31 @@
   "use strict";
   window.DsmPackageApps = window.DsmPackageApps || {};
   window.DsmPackageApps["__PACKAGE__"] = {
-    mount(root) {
+    // ctx.t(key) returns text from i18n/messages/<locale>.json in DSM's language.
+    // ctx.portal exists only with `portal:` in dsm-package.yaml; its panel
+    // shows the DSM Application Portal link, or the alias form to administrators.
+    mount(root, ctx) {
       const app = document.createElement("main");
       app.className = "binary-app";
       const title = document.createElement("h1");
-      title.textContent = "Binary App";
+      title.textContent = ctx.t("app.title");
       const description = document.createElement("p");
-      description.textContent = "Your prebuilt CGI is packaged in this DSM application.";
+      description.textContent = ctx.t("app.description");
       app.append(title, description);
+      let portalPanel = null;
+      if (ctx.portal) {
+        const portal = document.createElement("section");
+        portal.setAttribute("class", "dsmapp-portal");
+        app.append(portal);
+        portalPanel = ctx.portal.mountPanel(portal);
+      }
       root.append(app);
-      return { unmount() { app.remove(); } };
+      return {
+        unmount() {
+          if (portalPanel) portalPanel.dispose();
+          app.remove();
+        },
+      };
     },
   };
 })();