@synopackageland/templates 0.15.1 → 0.16.0

package/README.md

@@ -38,12 +38,13 @@ calls each one from the generated script of the same name (`synopkgland skill sh
 The placeholders `__PACKAGE__` (also the Go module path), `__DISPLAY_NAME__` and
 `__BACKGROUND_ENABLED__` are substituted by `init`.
 
-`backend/go.mod` requires `github.com/synopackageland/syno-pkg-land-sdk v0.15.1`; that line is
+`backend/go.mod` requires `github.com/synopackageland/syno-pkg-land-sdk v0.16.0`; that line is
 the single source of the SDK version and `frontend/package.json` pins
 `@synopackageland/sdk` to the same version. Python and Node.js name it in
 `backend.sdk`, Rust in the `syno-pkg-land-app` tag of `backend/Cargo.toml`
-(and `Cargo.lock`); all of them pin 0.15.1. The Vue frontend pins
-`@synopackageland/ui` 0.11.0.
+(and `Cargo.lock`); all of them pin 0.16.0. The Vue frontend pins
+`@synopackageland/ui` 0.12.0. SDK 0.16.0 accepts UI `>=0.10.1 <0.13.0`,
+so no UI peer override is needed. Tests use jsdom 30 for UI floating-layer styles.
 
 ## Notice writer
 
@@ -76,7 +77,8 @@ Without `SYNOPKGLAND_SDK_DIR` the combinations use the released SDK that
 `backend/go.mod` and `frontend/package.json` pin. With it, `assemble.sh` adds
 `replace github.com/synopackageland/syno-pkg-land-sdk => $SYNOPKGLAND_SDK_DIR`
 and installs `$SYNOPKGLAND_SDK_DIR/ts` as an `npm pack` tarball (not a link, so Vue
-resolves once). With `SYNOPKGLAND_UI_TARBALL` set it installs that tarball as
+resolves once). Set `SYNOPKGLAND_SDK_TARBALL` to a published tarball to test that
+release without rebuilding the SDK frontend. With `SYNOPKGLAND_UI_TARBALL` set it installs that tarball as
 `@synopackageland/ui`, for a UI version not yet on npm.
 The Python and Node.js combinations need `SYNOPKGLAND_SDK_DIR` (its `python/`,
 and `node/` built with `npm ci && npm run build`) for their App SDK, and the

package/package.json

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

package/templates/_shared/AGENTS.md

@@ -234,8 +234,9 @@ sweep forward the cancel instead of admitting it.
   repeats the original request on repeated IDs. Review it in the SDK's delegate
   package 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.
+- Verify the wizard on your own DSM release over an SSH local forward. The
+  template ships the wizard contract; it is not proof of every DSM release or of
+  full writer/reboot behavior.
 
 ## Go backend
 

package/templates/binary/ui/app.css

@@ -1,4 +1,21 @@
-:root { font-family: system-ui, sans-serif; color: #1e293b; background: #f8fafc; }
-.binary-app { padding: 2rem; }
-.binary-app h1 { font-size: 1.5rem; }
-.binary-app p { line-height: 1.6; }
+/* Static UI subset from @synopackageland/ui 0.12.0 dsm7-embedded theme. */
+.binary-app {
+  --ui-font-sans: Verdana, Arial, "Microsoft JhengHei", "Microsoft YaHei", Meiryo, sans-serif;
+  --ui-font-size: 13px;
+  --ui-font-size-title: 16px;
+  --ui-line-height: 20px;
+  --ui-text: #414b55;
+  --ui-surface: #fff;
+  --ui-space-2: 8px;
+  --ui-space-5: 20px;
+  --ui-space-6: 24px;
+  box-sizing: border-box;
+  min-height: 100%;
+  padding: var(--ui-space-5) var(--ui-space-6);
+  font: var(--ui-font-size)/var(--ui-line-height) var(--ui-font-sans);
+  color: var(--ui-text);
+  background: var(--ui-surface);
+  overflow-wrap: anywhere;
+}
+.binary-app h1 { margin: 0 0 var(--ui-space-2); font-size: var(--ui-font-size-title); font-weight: 600; }
+.binary-app p { margin: 0; }

package/templates/compose/dsm-package.yaml

@@ -14,7 +14,7 @@ compose:
   web: {service: web, port: 8080, health: {path: /, status: 200}}
   network: {egress: isolated}
 identity_gateway:
-  sdk: 0.15.1
+  sdk: 0.16.0
   mode: none
   listen: {http: 28000}
 # Web Apps default to new-page through the shared app-launch resolver.

package/templates/native-go/README.md

@@ -378,6 +378,21 @@ account or other packages. An upgrade never deletes anything. Do not write your
 `synopkgland inspect` flags a deleting script that lacks the upgrade guard
 or deletes outside the package's own folders.
 
+## Shared Folder access
+
+A `install.sharedFolder` in `dsm-package.yaml` lets the administrator pick a folder in the
+install wizard, but DSM does not give the package account access to a picked folder. The
+backend reports the real state: the `sharedfolder.status` operation (administrators only
+unless you change `permissions.json`) returns each folder with what the App needs, what the
+package account has (`none`, `read`, `write`) and a `state` (`ready`, `pending`, `missing`,
+`ambiguous`). `cfg.SharedFolderPath(key)` returns the path or an error that names the
+Control Panel step instead of failing on a file read. Keep `SharedFolderRequired` in
+`cmd/app/main.go` equal to the permission in `dsm-package.yaml`. Set `StorageAdapter` to
+apply a changed path (a re-picked folder, a moved volume) once; it runs only after access is
+granted. The Vue template shows the `SharedFolderSettings` section, which offers
+**Grant access** to an administrator and otherwise explains the Control Panel steps. See the
+SDK's `docs/shared-folder.md` for the whole flow.
+
 ## Support matrix
 
 | | Status |

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

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

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

@@ -20,6 +20,7 @@ import (
 	"github.com/synopackageland/syno-pkg-land-sdk/dsm"
 	"github.com/synopackageland/syno-pkg-land-sdk/filestation"
 	standaloneidentity "github.com/synopackageland/syno-pkg-land-sdk/identity"
+	"github.com/synopackageland/syno-pkg-land-sdk/sharedfolder"
 
 	appapi "__PACKAGE__/internal/api"
 	"__PACKAGE__/internal/app"
@@ -100,6 +101,9 @@ func main() {
 		DataDir:        "/var/packages/" + packageID + "/var",
 		Portal:         portal != "",
 		PortalExecutor: portal == "executor",
+		// install.sharedFolder in dsm-package.yaml: `synopkgland init --shared-folder`
+		// writes key "shared" with permission rw. Keep this equal to it.
+		SharedFolderRequired: map[string]sharedfolder.Access{"shared": sharedfolder.Write},
 	}
 	if _, err := app.ParseDelegateConfig(cfg); err != nil {
 		log.Fatal(err)

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

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

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

@@ -1,4 +1,4 @@
-github.com/synopackageland/syno-pkg-land-sdk v0.15.1 h1:RxG9aWn6PpAe/0o4jkbfDekrVImuIMSfx21X3lcnn24=
-github.com/synopackageland/syno-pkg-land-sdk v0.15.1/go.mod h1:msR4MhJQnVZ8NKLb0E/1K79ldZUvcOJmWhKq+gPEa+4=
+github.com/synopackageland/syno-pkg-land-sdk v0.16.0 h1:9MYFliraGfCE+1TXyFQD6s/YPMBMhGbj4bY+HHh9Y08=
+github.com/synopackageland/syno-pkg-land-sdk v0.16.0/go.mod h1:vixf5Lo4PssQDGU5zam0Mb5sFu9wPUP4Ck36BMAVbNc=
 golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
 golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=

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

@@ -20,6 +20,7 @@ import (
 
 	"github.com/synopackageland/syno-pkg-land-sdk/api"
 	"github.com/synopackageland/syno-pkg-land-sdk/filestation"
+	"github.com/synopackageland/syno-pkg-land-sdk/sharedfolder"
 )
 
 // Config is fixed at build time and startup, never taken from a request.
@@ -37,6 +38,14 @@ type Config struct {
 	DataDir string
 	// VolumeRoot is where /volumeN lives; empty means "/". Tests set it.
 	VolumeRoot string
+	// SharedFolderRequired is the access each Shared Folder key needs. Keep it
+	// equal to install.sharedFolder.permission in dsm-package.yaml: ro is
+	// sharedfolder.Read, rw is sharedfolder.Write.
+	SharedFolderRequired map[string]sharedfolder.Access
+	// StorageAdapter, when set, hands a Shared Folder's path to the App's own
+	// storage settings (a Local storage, a library root): the first time the
+	// folder is ready, and again whenever its path changes. Make it idempotent.
+	StorageAdapter func(ctx context.Context, key, path string) error
 	// Portal serves portal.status; PortalExecutor adds the executor's entry
 	// below DSM 7.2. PortalConfig overrides DSM's saved AppPortal.json path in
 	// tests.
@@ -49,6 +58,7 @@ func Routes(cfg Config) []api.Route {
 	routes := cfg.delegateRoutes()
 	routes = append(routes, []api.Route{
 		api.Handle("app.status", cfg.status),
+		api.Handle("sharedfolder.status", cfg.sharedFolderStatus),
 		api.Handle("greeting.get", cfg.getGreeting),
 		api.Handle("greeting.set", cfg.setGreeting),
 	}...)
@@ -59,7 +69,7 @@ func Routes(cfg Config) []api.Route {
 }
 
 func (cfg Config) status(_ context.Context, caller api.Caller, _ json.RawMessage) (any, error) {
-	return cfg.withSharedFolders(map[string]any{
+	return map[string]any{
 		"package":    cfg.PackageID,
 		"version":    cfg.Version,
 		"user":       caller.User(),
@@ -68,7 +78,7 @@ func (cfg Config) status(_ context.Context, caller api.Caller, _ json.RawMessage
 		"go_version": runtime.Version(),
 		"platform":   runtime.GOOS + "/" + runtime.GOARCH,
 		"time":       time.Now().UTC().Format(time.RFC3339),
-	}), nil
+	}, nil
 }
 
 type greeting struct {

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

@@ -107,9 +107,10 @@ var (
 var sampleOutcome = map[string]string{}
 
 var sampleParams = map[string]string{
-	"app.status":   `{}`,
-	"greeting.get": `{}`,
-	"greeting.set": `{"text":"Hi"}`,
+	"app.status":          `{}`,
+	"sharedfolder.status": `{}`,
+	"greeting.get":        `{}`,
+	"greeting.set":        `{"text":"Hi"}`,
 }
 
 func TestEveryRouteHasSampleParamsAndNoneIsPublic(t *testing.T) {

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

@@ -1,144 +1,54 @@
 package app
 
 import (
+	"context"
 	"encoding/json"
-	"errors"
-	"fmt"
-	"io/fs"
-	"os"
-	"path/filepath"
-	"sort"
-	"strings"
-	"syscall"
-)
-
-// The install wizard stores the chosen Shared Folder's *name* in
-// <DataDir>/config.json (see dsm-package.yaml install.sharedFolder). The path
-// is resolved on every call, so a Shared Folder moved to another volume keeps
-// working. config.json is written by the package's postinst/postupgrade, not
-// by the app.
 
-var (
-	ErrSharedFolderNotFound  = errors.New("shared folder not found on any volume")
-	ErrSharedFolderAmbiguous = errors.New("shared folder name matches more than one volume")
+	"github.com/synopackageland/syno-pkg-land-sdk/api"
+	"github.com/synopackageland/syno-pkg-land-sdk/sharedfolder"
 )
 
-// SharedFolder says where one configured Shared Folder is right now and what
-// the package account may do there.
-type SharedFolder struct {
-	Key      string `json:"key"`
-	Name     string `json:"name"`
-	Path     string `json:"path,omitempty"`
-	Exists   bool   `json:"exists"`
-	Readable bool   `json:"readable"`
-	Writable bool   `json:"writable"`
-	Error    string `json:"error,omitempty"`
-}
-
-func validShareName(name string) bool {
-	return name != "" && !strings.ContainsAny(name, "/\\\x00") && !strings.Contains(name, "..") &&
-		!strings.HasPrefix(name, "@") && !strings.HasPrefix(name, ".")
-}
-
-// ReadSharedFolders returns the Shared Folder names the installer stored, by
-// key. A package without config.json has none.
-func ReadSharedFolders(dataDir string) (map[string]string, error) {
-	data, err := os.ReadFile(filepath.Join(dataDir, "config.json"))
-	if errors.Is(err, fs.ErrNotExist) {
-		return nil, nil
-	}
-	if err != nil {
-		return nil, err
-	}
-	var cfg struct {
-		Schema        int               `json:"schema"`
-		SharedFolders map[string]string `json:"shared_folders"`
-	}
-	if err := json.Unmarshal(data, &cfg); err != nil {
-		return nil, fmt.Errorf("config.json: %w", err)
-	}
-	if cfg.Schema != 1 {
-		return nil, fmt.Errorf("config.json: unsupported schema %d", cfg.Schema)
-	}
-	for key, name := range cfg.SharedFolders {
-		if !validShareName(name) {
-			return nil, fmt.Errorf("config.json: invalid shared folder name for %q", key)
-		}
-	}
-	return cfg.SharedFolders, nil
-}
-
-// ResolveSharedFolder finds /volumeN/<name> under root ("/" on a NAS).
-func ResolveSharedFolder(root, name string) (string, error) {
-	if !validShareName(name) {
-		return "", fmt.Errorf("invalid shared folder name %q", name)
-	}
-	volumes, err := filepath.Glob(filepath.Join(root, "volume[0-9]*"))
-	if err != nil {
-		return "", err
-	}
-	var found []string
-	for _, volume := range volumes {
-		path := filepath.Join(volume, name)
-		if info, err := os.Stat(path); err == nil && info.IsDir() {
-			found = append(found, path)
-		}
-	}
-	switch len(found) {
-	case 0:
-		return "", ErrSharedFolderNotFound
-	case 1:
-		return found[0], nil
-	}
-	return "", ErrSharedFolderAmbiguous
+// The install wizard stores the chosen Shared Folder's *name* in
+// <DataDir>/config.json (see dsm-package.yaml install.sharedFolder). DSM does
+// not give the package account access to a folder chosen at install time: an
+// administrator grants it in Control Panel (or with one click in the settings
+// page). The SDK's sharedfolder package measures what the account may do, so
+// this route, the settings page and any daemon read one state.
+
+// sharedFolders is the SDK's view of this package's Shared Folders.
+func (cfg Config) sharedFolders() sharedfolder.Config {
+	return sharedfolder.Config{DataDir: cfg.DataDir, Root: cfg.VolumeRoot, Required: cfg.SharedFolderRequired}
 }
 
-const (
-	accessRead  = 0x4 // R_OK
-	accessWrite = 0x2 // W_OK
-	accessExec  = 0x1 // X_OK
-)
-
-// SharedFolders reports every configured Shared Folder, sorted by key. The
-// error is a corrupt config.json.
-func (cfg Config) SharedFolders() ([]SharedFolder, error) {
-	names, err := ReadSharedFolders(cfg.DataDir)
+// sharedFolderStatus answers the settings page: each folder, what the package
+// account has and what the App declared it needs, and whether an
+// administrator still has to grant. Administrators only, as the default
+// permissions say; list the method in internal/api/permissions.json to let
+// every DSM user read it.
+func (cfg Config) sharedFolderStatus(ctx context.Context, _ api.Caller, _ json.RawMessage) (any, error) {
+	status, err := cfg.sharedFolders().Status()
 	if err != nil {
 		return nil, err
 	}
-	root := cfg.VolumeRoot
-	if root == "" {
-		root = "/"
-	}
-	keys := make([]string, 0, len(names))
-	for key := range names {
-		keys = append(keys, key)
-	}
-	sort.Strings(keys)
-	folders := make([]SharedFolder, 0, len(keys))
-	for _, key := range keys {
-		folder := SharedFolder{Key: key, Name: names[key]}
-		path, err := ResolveSharedFolder(root, folder.Name)
-		if err != nil {
-			folder.Error = err.Error()
-		} else {
-			folder.Path, folder.Exists = path, true
-			folder.Readable = syscall.Access(path, accessRead|accessExec) == nil
-			folder.Writable = syscall.Access(path, accessWrite|accessExec) == nil
+	// The App's own storage follows a changed path (another folder chosen,
+	// the share moved to another volume) here, the first time anything reads it.
+	if cfg.StorageAdapter != nil {
+		for _, folder := range status.Folders {
+			if folder.State == sharedfolder.Ready {
+				if _, err := cfg.sharedFolders().Sync(folder.Key, func(path string) error {
+					return cfg.StorageAdapter(ctx, folder.Key, path)
+				}); err != nil {
+					return nil, sharedfolder.APIError(err)
+				}
+			}
 		}
-		folders = append(folders, folder)
 	}
-	return folders, nil
+	return status, nil
 }
 
-// withSharedFolders adds the configured Shared Folders to an app.status
-// answer; a package that configures none is answered exactly as before.
-func (cfg Config) withSharedFolders(status map[string]any) map[string]any {
-	folders, err := cfg.SharedFolders()
-	if err != nil {
-		status["shared_folders_error"] = err.Error()
-	} else if len(folders) > 0 {
-		status["shared_folders"] = folders
-	}
-	return status
+// SharedFolderPath is what a daemon calls before it touches the folder: the
+// path once the account has the declared access, otherwise an error naming
+// what to grant, never a failed file read.
+func (cfg Config) SharedFolderPath(key string) (string, error) {
+	return cfg.sharedFolders().Require(key)
 }