@synopackageland/templates 0.0.0-stage → 0.9.1

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

@@ -0,0 +1,7 @@
+package app
+
+import "github.com/synopackageland/syno-pkg-land-sdk/api"
+
+// backgroundRoutes serves the owner-scoped background job API. Jobs run
+// in the package-user worker unit (conf/systemd), never as root.
+func (cfg Config) backgroundRoutes() []api.Route { return BackgroundRoutes(cfg.DataDir) }

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

@@ -0,0 +1,87 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"github.com/synopackageland/syno-pkg-land-sdk/api"
+	"github.com/synopackageland/syno-pkg-land-sdk/background"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+)
+
+func init() {
+	// The generic route tests need valid params for every background route.
+	// The fixture has no DSM cookie; import is refused before reading a file.
+	// No jobs or schedules exist in its fresh data directory.
+	const id = `{"id":"missing"}`
+	sampleParams["bg.jobs.purge"] = `{"owner":{"user":"missing","uid":"9999"}}`
+	sampleParams["bg.schedules.list"] = `{}`
+	sampleParams["bg.schedules.create"] = `{"key":"schedule","jobId":"missing","intervalSeconds":3600,"consent":true}`
+	sampleParams["bg.schedules.disable"] = id
+	sampleParams["bg.schedules.delete"] = id
+	sampleParams["bg.schedules.enable"] = `{"id":"missing","consent":true}`
+	sampleOutcome["bg.schedules.create"] = "not_found"
+	sampleOutcome["bg.schedules.disable"] = "not_found"
+	sampleOutcome["bg.schedules.delete"] = "not_found"
+	sampleOutcome["bg.schedules.enable"] = "not_found"
+	sampleParams["bg.status"] = `{}`
+	sampleParams["bg.browse"] = `{}`
+	sampleParams["bg.jobs.submit"] = `{"key":"k1","folder":"/share","relative":"a.bin"}`
+	sampleParams["bg.jobs.list"] = `{}`
+	sampleParams["bg.jobs.get"] = id
+	sampleParams["bg.jobs.cancel"] = 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.result"] = "not_found"
+}
+
+func TestBackgroundBusyErrorCode(t *testing.T) {
+	err := backgroundError(background.ErrBusy)
+	var e *api.Error
+	if !errors.As(err, &e) || e.Code != "jobs_busy" {
+		t.Fatalf("busy mapping: %v", err)
+	}
+}
+
+func TestBackgroundRequestSubmitBusyAndProductionConstruction(t *testing.T) {
+	e := newBgEnv(t)
+	dir := filepath.Join(t.TempDir(), "background")
+	e.store = background.NewRequestStore(dir)
+	if _, err := e.store.List(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	f, err := os.OpenFile(filepath.Join(dir, "lock"), os.O_RDWR, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close()
+	if err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX|syscall.LOCK_NB); err != nil {
+		t.Fatal(err)
+	}
+	defer syscall.Flock(int(f.Fd()), syscall.LOCK_UN)
+	start := time.Now()
+	code, out := e.call(alice, "bg.jobs.submit", bgSample["bg.jobs.submit"])
+	if code != "jobs_busy" || time.Since(start) > background.RequestLockTimeout+time.Second {
+		t.Fatalf("busy submit: %s %+v", code, out)
+	}
+	// The actual production assembly must use the same bounded wait policy.
+	srv, err := api.NewServerWithPermissions(alice, []byte(`{"schema":1,"default":"administrators","methods":{}}`), BackgroundRoutes(filepath.Dir(dir))...)
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := httptest.NewRequest("POST", "/api.cgi", strings.NewReader(`{"method":"bg.jobs.list","params":{}}`))
+	r.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	srv.ServeHTTP(w, r)
+	if !strings.Contains(w.Body.String(), `"jobs_busy"`) {
+		t.Fatal(w.Body.String())
+	}
+}

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

@@ -0,0 +1,20 @@
+// @vitest-environment jsdom
+import {expect,test,vi} from 'vitest'
+import {nextTick} from 'vue'
+import {mount} from '../src/main'
+import type {Context} from '@synopackageland/sdk'
+async function settle(){for(let i=0;i<20;i++){await Promise.resolve();await nextTick()}}
+// The CLI turns the background page on for jobs (and delegate) projects only.
+test('a jobs project mounts the background panel for the signed-in user',async()=>{
+ const call=vi.fn(async(method:string)=>{
+  if(method==='app.status')return {package:'Jobs',version:'1',user:'alice',admin:false}
+  throw {code:'unknown_method'}
+ })
+ const root=document.createElement('div');document.body.append(root)
+ const app=mount(root,{locale:'en',call,reopen:()=>()=>{}} as unknown as Context)
+ try{
+  await settle()
+  expect(call.mock.calls.some(([method])=>method.startsWith('bg.'))).toBe(true)
+  expect(root.querySelector('[data-page="background"]')).not.toBeNull()
+ }finally{app.unmount();root.remove()}
+})

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

@@ -0,0 +1,128 @@
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/synopackageland/syno-pkg-land-sdk/api"
+	"github.com/synopackageland/syno-pkg-land-sdk/delegate"
+)
+
+func (cfg Config) rootRoutes() []api.Route {
+	return []api.Route{
+		api.Handle("executor.control", cfg.executorControl),
+		api.Handle("executor.status", cfg.executorStatus),
+		api.HandleRequest("root.run", cfg.executorRootRun),
+	}
+}
+
+// API permissions default to administrators for unlisted methods. Check here
+// too: control mutates the fixed package-owned control file before DSM run.
+func (cfg Config) executorControl(_ context.Context, caller api.Caller, raw json.RawMessage) (any, error) {
+	if !caller.Admin() {
+		return nil, errors.New("admin_required")
+	}
+	var in struct {
+		Action string `json:"action"`
+	}
+	if err := decodeParams(raw, &in); err != nil {
+		return nil, err
+	}
+	if in.Action != "start" && in.Action != "stop" && in.Action != "purge" {
+		return nil, api.BadRequest("executor_control_invalid")
+	}
+	dir := filepath.Join(cfg.DataDir, "executor")
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		return nil, err
+	}
+	info, err := os.Lstat(dir)
+	if err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+		return nil, errors.New("executor_control_directory_invalid")
+	}
+	if err := writeFileAtomic(filepath.Join(dir, "control"), []byte(in.Action)); err != nil {
+		return nil, err
+	}
+	return map[string]bool{"written": true}, nil
+}
+
+// The executor closes its socket while paused: the package is stopped, or an
+// upgrade changed the pins and awaits administrator approval.
+func (cfg Config) executorStatus(ctx context.Context, _ api.Caller, _ json.RawMessage) (any, error) {
+	var status json.RawMessage
+	err := cfg.executor().Call(ctx, "status", nil, nil, &status)
+	var refusal *api.Error
+	if errors.As(err, &refusal) && refusal.Code == delegate.CodeExecutorUnavailable {
+		next := "Start the package."
+		if cfg.startRequested() {
+			next = "The package is running: an administrator approves background access again in Administrator setup; the executor log names the cause."
+		}
+		return map[string]any{"ready": false, "state": "paused", "reason": "executor_not_listening", "next": next}, nil
+	}
+	return status, err
+}
+
+// Package start and stop write the lifecycle mailbox; its last request tells a
+// stopped package from a running one whose executor stays paused.
+func (cfg Config) startRequested() bool {
+	f, err := os.Open(filepath.Join(cfg.DataDir, "executor", "control"))
+	if err != nil {
+		return false
+	}
+	defer f.Close()
+	b := make([]byte, 16)
+	n, _ := f.Read(b)
+	return strings.TrimSpace(string(b[:n])) == "start"
+}
+
+func (cfg Config) executorRootRun(ctx context.Context, caller api.Caller, req *http.Request, raw json.RawMessage) (any, error) {
+	if !caller.Admin() {
+		return nil, errors.New("admin_required")
+	}
+	var in struct {
+		Name string `json:"name"`
+	}
+	if err := decodeParams(raw, &in); err != nil {
+		return nil, err
+	}
+	// Executor independently verifies both session values and administrator identity.
+	auth, err := api.DSMSession(req)
+	if err != nil {
+		return nil, err
+	}
+	if err := cfg.executorHoldsThisBuild(ctx); err != nil {
+		return nil, err
+	}
+	var out json.RawMessage
+	if err := cfg.executor().Call(ctx, "root.run", auth, map[string]string{"name": in.Name}, &out); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// executorHoldsThisBuild refuses, as delegate does, an executor pinned to
+// another build's policy or executor: its approved scripts are not this build's.
+func (cfg Config) executorHoldsThisBuild(ctx context.Context) error {
+	var pins delegate.ExecutorStatus
+	if err := cfg.executor().Call(ctx, "status", nil, nil, &pins); err != nil {
+		return err
+	}
+	if (cfg.ExecutorDigest != "" && pins.ExecutorDigest != cfg.ExecutorDigest) || (cfg.PolicyDigest != "" && pins.PolicyDigest != cfg.PolicyDigest) {
+		return &api.Error{Code: delegate.CodePolicyDenied, Message: "the executor holds another build's approved policy; an administrator approves this build in Administrator setup"}
+	}
+	return nil
+}
+
+// executorSocketBase is a variable so tests can use a temporary directory.
+var executorSocketBase = "/run/synopkgland"
+
+// executor keeps the executor's protocol v1 refusal codes (POLICY_DENIED,
+// EXECUTOR_UNAVAILABLE, ...) as the API error code.
+func (cfg Config) executor() *delegate.Client {
+	return &delegate.Client{Socket: filepath.Join(executorSocketBase, cfg.PackageID, "executor.sock"), Timeout: 30 * time.Second}
+}

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

@@ -0,0 +1,237 @@
+package app
+
+import (
+	"bufio"
+	"encoding/json"
+	"net"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+
+	appapi "__PACKAGE__/internal/api"
+)
+
+func init() {
+	sampleParams["executor.control"] = `{"action":"stop"}`
+	sampleParams["executor.status"] = `{}`
+	sampleParams["root.run"] = `{"name":"whoami"}`
+	sampleOutcome["root.run"] = "session_required"
+}
+
+func TestExecutorControlAcceptsOnlyFixedActions(t *testing.T) {
+	cfg := testConfig(t)
+	for _, action := range []string{"start", "stop", "purge"} {
+		code, out := call(t, cfg, alice, "executor.control", `{"action":"`+action+`"}`)
+		if code != "" {
+			t.Fatalf("%s: %s %v", action, code, out)
+		}
+		b, err := os.ReadFile(filepath.Join(cfg.DataDir, "executor/control"))
+		if err != nil || string(b) != action {
+			t.Fatalf("control was not written: %s %v", b, err)
+		}
+	}
+	for _, raw := range []string{`{"action":"start;id"}`, `{"action":"start\nstop"}`, `{"action":""}`, `{"action":"stop","path":"/etc/passwd"}`} {
+		if code, _ := call(t, cfg, alice, "executor.control", raw); code != "bad_request" {
+			t.Fatalf("accepted %s: %s", raw, code)
+		}
+	}
+}
+
+func TestExecutorControlRejectsSymlinkDirectory(t *testing.T) {
+	cfg := testConfig(t)
+	outside := t.TempDir()
+	if err := os.Symlink(outside, filepath.Join(cfg.DataDir, "executor")); err != nil {
+		t.Fatal(err)
+	}
+	if code, _ := call(t, cfg, alice, "executor.control", `{"action":"stop"}`); code == "" {
+		t.Fatal("accepted symlink")
+	}
+	if _, err := os.Stat(filepath.Join(outside, "control")); !os.IsNotExist(err) {
+		t.Fatal("wrote outside data directory")
+	}
+}
+
+func TestExecutorRootRunRequiresCurrentDSMCookie(t *testing.T) {
+	t.Setenv("HTTP_COOKIE", "")
+	if code, _ := call(t, testConfig(t), alice, "root.run", `{"name":"whoami"}`); code == "" {
+		t.Fatal("root.run accepted absent DSM cookie")
+	}
+}
+
+// The executor closes its listener while paused (package stopped, or pins
+// awaiting administrator approval). Status then answers, not "internal".
+func TestExecutorStatusReportsAPausedExecutor(t *testing.T) {
+	cfg := testConfig(t)
+	useExecutorSocketBase(t)
+	check := func(name string) {
+		t.Helper()
+		code, envelope := call(t, cfg, alice, "executor.status", `{}`)
+		out, _ := envelope["data"].(map[string]any)
+		if code != "" || out["ready"] != false || out["state"] != "paused" || out["reason"] != "executor_not_listening" || out["next"] == "" || out["next"] == nil {
+			t.Fatalf("%s: %s %v", name, code, out)
+		}
+	}
+	check("no socket")
+	if code, _ := call(t, cfg, bob, "executor.status", `{}`); code != "" {
+		t.Fatal("authenticated user cannot read a paused status", code)
+	}
+	dir := filepath.Join(executorSocketBase, cfg.PackageID)
+	os.MkdirAll(dir, 0700)
+	ln, err := net.ListenUnix("unix", &net.UnixAddr{Name: filepath.Join(dir, "executor.sock"), Net: "unix"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	ln.SetUnlinkOnClose(false)
+	ln.Close()
+	check("closed listener")
+}
+
+// next follows the last lifecycle request: a running package needs approval
+// again, not a start.
+func TestExecutorStatusNextFollowsTheLifecycleRequest(t *testing.T) {
+	cfg := testConfig(t)
+	useExecutorSocketBase(t)
+	next := func() string {
+		t.Helper()
+		_, envelope := call(t, cfg, alice, "executor.status", `{}`)
+		out, _ := envelope["data"].(map[string]any)
+		s, _ := out["next"].(string)
+		return s
+	}
+	if !strings.HasPrefix(next(), "Start the package.") {
+		t.Fatal("no request:", next())
+	}
+	mailbox := filepath.Join(cfg.DataDir, "executor")
+	os.MkdirAll(mailbox, 0700)
+	for request, start := range map[string]bool{"stop\n": true, "start\n": false, "start": false} {
+		os.WriteFile(filepath.Join(mailbox, "control"), []byte(request), 0600)
+		if got := next(); strings.HasPrefix(got, "Start the package") != start || got == "" {
+			t.Fatalf("%q: %s", request, got)
+		}
+	}
+}
+
+// fakeExecutor answers each v1 request with replies[op] and records the ops.
+type fakeExecutor struct {
+	mu  sync.Mutex
+	ops []string
+}
+
+func (f *fakeExecutor) received() []string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return append([]string(nil), f.ops...)
+}
+
+func startFakeExecutor(t *testing.T, cfg Config, replies map[string]string) *fakeExecutor {
+	t.Helper()
+	useExecutorSocketBase(t)
+	dir := filepath.Join(executorSocketBase, cfg.PackageID)
+	if err := os.MkdirAll(dir, 0700); err != nil {
+		t.Fatal(err)
+	}
+	ln, err := net.Listen("unix", filepath.Join(dir, "executor.sock"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { ln.Close() })
+	f := &fakeExecutor{}
+	go func() {
+		for {
+			conn, err := ln.Accept()
+			if err != nil {
+				return
+			}
+			var req struct{ Op string }
+			line, _ := bufio.NewReader(conn).ReadBytes('\n')
+			json.Unmarshal(line, &req)
+			f.mu.Lock()
+			f.ops = append(f.ops, req.Op)
+			f.mu.Unlock()
+			conn.Write([]byte(replies[req.Op] + "\n"))
+			conn.Close()
+		}
+	}()
+	return f
+}
+
+// useExecutorSocketBase points the CGI at a short temporary directory: unix
+// socket paths are limited to about 100 bytes.
+func useExecutorSocketBase(t *testing.T) {
+	t.Helper()
+	previous := executorSocketBase
+	base, err := os.MkdirTemp("/tmp", "exec")
+	if err != nil {
+		t.Fatal(err)
+	}
+	executorSocketBase = base
+	t.Cleanup(func() { executorSocketBase = previous; os.RemoveAll(base) })
+}
+
+// rootRun calls root.run as an administrator with a current DSM session.
+func rootRun(t *testing.T, cfg Config, name string) (string, map[string]any) {
+	t.Helper()
+	permissions, err := appapi.Permissions()
+	if err != nil {
+		t.Fatal(err)
+	}
+	req := apiRequest("root.run", `{"name":"`+name+`"}`)
+	req.Header.Set("Cookie", "id=session")
+	req.Header.Set("X-SYNO-TOKEN", "token")
+	return serve(t, cfg, alice, req, permissions)
+}
+
+const readyStatus = `{"ok":true,"result":{"executor_digest":"e1","policy_digest":"p1","ready":true,"disabled":false,"version":"1"}}`
+
+func pinnedConfig(t *testing.T) Config {
+	cfg := testConfig(t)
+	cfg.ExecutorDigest, cfg.PolicyDigest = "e1", "p1"
+	return cfg
+}
+
+func TestExecutorRootRunRunsWhenTheExecutorHoldsThisBuildsPins(t *testing.T) {
+	cfg := pinnedConfig(t)
+	startFakeExecutor(t, cfg, map[string]string{"status": readyStatus, "root.run": `{"ok":true,"result":{"output":"0\n"}}`})
+	code, out := rootRun(t, cfg, "whoami")
+	if data, _ := out["data"].(map[string]any); code != "" || data["output"] != "0\n" {
+		t.Fatalf("%s %v", code, out)
+	}
+}
+
+// Like delegate: an executor pinned to another build's policy or executor
+// refuses the operation, it does not run it.
+func TestExecutorRootRunRefusesAnExecutorPinnedToAnotherBuild(t *testing.T) {
+	for name, status := range map[string]string{
+		"policy":   strings.Replace(readyStatus, `"p1"`, `"p2"`, 1),
+		"executor": strings.Replace(readyStatus, `"e1"`, `"e2"`, 1),
+	} {
+		cfg := pinnedConfig(t)
+		f := startFakeExecutor(t, cfg, map[string]string{"status": status, "root.run": `{"ok":true,"result":{"output":"0\n"}}`})
+		if code, out := rootRun(t, cfg, "whoami"); code != "POLICY_DENIED" {
+			t.Errorf("%s digest mismatch: %q %v", name, code, out)
+		}
+		for _, op := range f.received() {
+			if op == "root.run" {
+				t.Errorf("%s digest mismatch: root.run reached the executor", name)
+			}
+		}
+	}
+}
+
+// Refusals keep the protocol v1 code (spec/protocol/v1/errors.json), never "internal".
+func TestExecutorRootRunReportsTheExecutorsRefusalCode(t *testing.T) {
+	cfg := pinnedConfig(t)
+	useExecutorSocketBase(t)
+	if code, _ := rootRun(t, cfg, "whoami"); code != "EXECUTOR_UNAVAILABLE" {
+		t.Errorf("paused or awaiting approval (no socket): %q", code)
+	}
+	for _, refusal := range []string{"POLICY_DENIED", "INVALID_REQUEST", "EXECUTOR_PAUSED", "ROOT_FAILED", "ADMIN_REQUIRED"} {
+		cfg := pinnedConfig(t)
+		startFakeExecutor(t, cfg, map[string]string{"status": readyStatus, "root.run": `{"ok":false,"code":"` + refusal + `","message":"refused"}`})
+		if code, out := rootRun(t, cfg, "whoami"); code != refusal {
+			t.Errorf("%s: %q %v", refusal, code, out)
+		}
+	}
+}

package/templates/native-go-root-ops/root/whoami.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+set -eu
+id -u

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

@@ -0,0 +1,51 @@
+# Native Go with Vue
+
+Edit `frontend/src/App.vue` and `main.ts` to build a DSM-window app with the
+public `@synopackageland/ui` components and embedded theme. The shell, sign-in,
+files, portal, jobs and delegate components come from `@synopackageland/sdk/vue`
+(types from `@synopackageland/sdk`); its version must equal the
+`github.com/synopackageland/syno-pkg-land-sdk` version in `backend/go.mod`. See
+<https://github.com/synopackageland/syno-pkg-land-sdk> for the components and their props.
+
+```sh
+cd frontend
+npm ci
+npm test
+npm run build
+```
+
+The base app reads package status and edits the package greeting through
+`ctx.call`. Each window has its own Vue mount, request state and host
+subscriptions; unmount disposes subscriptions and ignores late responses.
+
+`--with root-ops` adds the existing DSM approval gate for fixed `root/*.sh`
+operations. `--with jobs` adds package-account jobs and schedules; it combines with root-ops and files. `--with files` enables current-session File Station access,
+and the background picker uses the retained session provider.
+
+With `portal:` declared (`synopkgland add portal`, executor Apps only), the status page shows
+the SDK's `PortalSettings`: the DSM Application Portal link, the alias form
+for administrators, and the Control Panel shortcut.
+
+Use public library controls, the embedded theme, per-app modal scope and unique
+Vue ID prefixes. Backend route permissions and DSM checks remain authoritative.
+Generated build and unit tests do not establish NAS runtime acceptance.
+
+The manifest is dsm-package.yaml schema 2: backend.kind: go and capabilities.files: session, jobs: true, identity: standalone, rootOps: true. Use --with login to declare standalone identity. Existing projects use synopkgland add <cap>...; app entrypoints stay app-owned, SDK conflicts are refused. check, inspect, build, deploy and status accept --json.
+
+Use the installed `@synopackageland/ui`; package.json pins its version.
+`AppRoot` defaults to app modal scope and stays bounded at `height: 100%`;
+`AppLayout wide-layout="window"` keeps the DSM shell in window mode even when
+maximized. Only whole-page web/Portal apps should opt into document scope or
+`wide-layout="web"`. The DSM host sets the 700px minimum window width.
+Import `themes/dsm7-embedded.css` and assign each mount a unique
+`app.config.idPrefix` before mounting.
+
+Start with AGENTS.md, `synopkgland skill list` and `synopkgland skill path`.
+Read `synopkgland skill show ui-vue` for direct Vue component work and
+`synopkgland skill show ui-json` for optional declarative specs and their
+validate/render workflow. The existing host/backend lifecycle remains in place.
+
+For UI discovery, run `npx --no syno-pkg-land-ui catalog --json` and
+`npx --no syno-pkg-land-ui describe Button --json` from the installed frontend.
+Read its prompt and exported Vue docs/types before choosing component APIs.
+Use `syno-pkg-land-ui` directly in npm scripts; keep AI guidance version-independent.

package/templates/native-go-vue/frontend/DESIGN.md

@@ -0,0 +1,61 @@
+---
+name: Native DSM Vue template
+description: Existing package settings UI using the installed @synopackageland/ui.
+typography:
+  body:
+    fontFamily: "var(--ui-font-sans)"
+    fontSize: "13px"
+    lineHeight: 1.5
+  title:
+    fontSize: "20px"
+    fontWeight: 600
+  state:
+    fontSize: "15px"
+    fontWeight: 600
+spacing:
+  actions: "8px"
+  heading-gap: "16px"
+  section-gap: "24px"
+---
+
+# Design System: Native DSM Vue template
+
+Read `AGENTS.md` at the project root and `synopkgland skill show ui-vue` before UI edits.
+
+For UI discovery, run `npx --no syno-pkg-land-ui catalog --json` and
+`npx --no syno-pkg-land-ui describe Button --json` from the installed frontend.
+Read its prompt and exported Vue docs/types before choosing component APIs.
+Use `syno-pkg-land-ui` directly in npm scripts; keep AI guidance version-independent.
+
+## Overview
+
+The template runs inside a DSM package window. `AppShell` provides status and
+optional background navigation. The base page shows package status and a greeting
+editor; the root overlay adds its existing fixed-operation authorization gate.
+
+Use the installed `@synopackageland/ui` controls and `themes/dsm7-embedded.css`.
+The theme owns colors, typography, spacing and dialogs. Keep per-app modal scope,
+a unique Vue ID prefix and vertical scrolling at the DSM minimum window size.
+
+Refresh and save expose busy state and localized errors. Reopen refreshes status.
+Each mount owns its state; unmount unsubscribes from host events and ignores late
+responses. Backend route policies decide access.
+
+### Opt-in background schedules (S1-a)
+
+The `native-go-jobs` overlay extends this **Operate** surface within the inherited `AppRoot`, embedded theme, `SettingsSection`, Button and Callout system. It introduces no new palette or global tokens.
+
+- **Private-copy consent:** “Schedule this copy” is available for the signed-in owner's retained, successful, unscheduled job copy. “Private copy: {name}” identifies the input; “Repeat every” offers “Hour”, “Day” and “Week”. “Create schedule” stays disabled until the user checks “I agree to keep and reprocess this fixed copy as the package user. No new source files or personal ACLs are read.” The help explains the eight-schedule limit and that missed runs are recorded, never replayed.
+- **Ownership and recovery:** preserve user-and-UID owner isolation. Administrator rows expose “Owner: {user} (UID {uid})”. A worker change shows “The worker revision changed. An administrator must review and explicitly enable this schedule.” Only administrators, while background mode is on, see “Enable schedule”. Its confirmation names the exact private copy: “Enable the schedule for {name} with the current worker revision? I agree to reprocess this fixed copy. Past runs will not be replayed.” Actions are “Confirm enable” and “Cancel”.
+- **Layout:** schedule name/state, owner, next run, missed runs and warnings stack above a grouped, wrapping action row. Long names and copy wrap within the available width. Keep the inherited vertical scrolling at the minimum window size; do not squeeze schedules into one viewport. The labeled select and consent checkbox retain visible keyboard focus using existing theme tokens.
+- **Errors and cleanup:** danger alerts map known error codes to localized safe copy, with a localized fallback rather than raw server text. The catalogs cover nine locales. Preserve per-mount disposal: stop polling, dispose the picker, revoke result download URLs and prevent pending responses from restoring disposed state. Deletion confirmation explains that queued jobs cancel, running jobs drain and finished results remain.
+
+Evidence: `.herdr-project/syno-package-land-sdk-t-0129/library/ui-desktop.png` and `ui-minimum.png` are local component-fixture captures. The finish review disposition is **ship**, with all three material findings resolved. A fresh `normal1` NAS browser readback passed before the final UI adjustments; these captures validate the final adjustments locally and do not establish final DSM visual acceptance.
+
+## Do's and Don'ts
+
+- Do use existing public UI components, embedded theme tokens and state/recovery copy.
+- Do retain permission gating, readable loading/empty/error states and per-instance cleanup.
+- Do use the library's `Select`, `Checkbox`, `Input`, `Textarea`, `Form`, `FormItem`, `FilePicker` (`variant="compact"`, in the app locale) and `Link` for controls; there is no native `<input>` or `<a>`. Leave `Form` on its automatic direction (labels stack below 520px of container width) and let a `FormItem` bind its control, with no `direction="vertical"`, `role="group"` or `field.controlId`.
+- Do not infer authority from frontend observations or scheduler history.
+- Don't introduce a separate palette, component system or modal workaround around the library contract.