@synopackageland/templates 0.9.9 → 0.10.0

package/templates/native-go-vue/frontend/src/App.vue

@@ -1,8 +1,8 @@
 <script setup lang="ts">
 import {computed, onMounted, onUnmounted, ref, watch} from 'vue'
-import {AppRoot, ConfigProvider, Button, Callout, Form, FormActions, FormItem, SettingsSection, Textarea} from '@synopackageland/ui'
-import type {AppStatus, Context, ShellPage} from '@synopackageland/sdk'
-import {AppShell, BackgroundPanel, FilesPage, LoginPage, PortalSettings, createSession, shellPages, uiLocale} from '@synopackageland/sdk/vue'
+import {Button, Callout, Form, FormActions, FormItem, SettingsSection, Textarea} from '@synopackageland/ui'
+import {bridgeErrorCopy, type AppStatus, type Context, type ShellPage} from '@synopackageland/sdk'
+import {AppShell, BackgroundPanel, FilesPage, LoginPage, PortalSettings, createSession, shellPages} from '@synopackageland/sdk/vue'
 import {appCopy} from './i18n'
 import CapabilityPanels from './CapabilityPanels.vue'
 const props = defineProps<{ctx: Context}>()
@@ -17,17 +17,16 @@ let disposed = false
 let unsubscribe: (() => void) | undefined
 // The CLI substitutes this only for a declared package-account background worker.
 const backgroundEnabled = (('__BACKGROUND_ENABLED__') as string) === 'true'
-// In a DSM window, dialogs may leave the window as DSM's own do; a press on one
-// does not reach the window, so it brings the window to the front itself.
-const inDsmWindow = props.ctx.host?.platform().host === 'dsm'
-function toFront() {props.ctx.host.activateWindow()}
 const page = ref<ShellPage>('status')
 const pages = computed(() => shellPages({background:backgroundEnabled}))
+// Only a confirmed sign-in need replaces the App's pages; the sign-in page draws its own title.
+const signIn = computed(() => login.ready.value && login.enabled.value && !login.subject.value && {header: false as const})
 const subtitle = computed(() => app.value ? `${app.value.package} · ${app.value.user} · ${app.value.version}` : undefined)
 function message(e: unknown) {
  const code = (e as {code?: string})?.code || 'request_failed'
  const errors = copy.value.errors as Record<string, string>
- return (code !== 'request_failed' && errors[code]) || errors.request_failed!.replace('{code}', code)
+ // A bridge App's runtime adds codes (app_unavailable, a service's refusal) the SDK words.
+ return bridgeErrorCopy(e, props.ctx.locale) ?? ((code !== 'request_failed' && errors[code]) || errors.request_failed!.replace('{code}', code))
 }
 let again = false
 async function refresh() {
@@ -76,33 +75,29 @@ onUnmounted(()=>{disposed=true;unsubscribe?.();login.dispose();text.value=''})
 </script>
 
 <template>
- <AppRoot modal-scope="app" :dialog-bounds="inDsmWindow ? 'viewport' : 'app'" style="height: 100%" @activate="toFront">
-  <ConfigProvider :locale="uiLocale(ctx.locale)">
-  <LoginPage v-if="login.ready.value && login.enabled.value && !login.subject.value" :session="login" :locale="ctx.locale" />
-  <AppShell v-else v-model="page" :locale="ctx.locale" :pages="pages" :description="subtitle">
-   <template #actions><Button variant="secondary" :disabled="busy" @click="refreshAll">{{ copy.refresh }}</Button><Button v-if="login.enabled.value" variant="secondary" :disabled="busy" @click="signOut">{{ copy.signOut }}</Button></template>
-   <div class="integration-app" :aria-busy="busy" :aria-label="copy.settings">
-    <Callout v-if="error" tone="danger" :title="copy.actionRequired"><span role="alert">{{ error }}</span></Callout>
-    <p v-if="notice" role="status">{{ notice }}</p>
-    <div data-page="status" v-show="page==='status'">
-     <SettingsSection :title="copy.statusTitle" :collapsible="false" :loading="busy && !app">
-      <p v-if="app">{{ app.package }} · {{ app.user }} · {{ app.version }}</p>
-      <p v-else-if="error" role="status">{{ copy.statusError }}</p>
-     </SettingsSection>
-     <PortalSettings v-if="ctx.portal && app" :key="portalKey" :portal="ctx.portal" />
-     <SettingsSection v-if="app?.admin" :title="copy.greeting" :collapsible="false">
-      <Form direction="vertical" @submit.prevent="save"><FormItem :label="copy.greeting"><Textarea v-model="text" :disabled="busy" /></FormItem>
-       <FormActions><Button variant="primary" :disabled="busy || !text.trim()" @click="save">{{ copy.save }}</Button></FormActions>
-      </Form>
-     </SettingsSection>
-    </div>
-    <CapabilityPanels v-if="app" ref="panels" :key="app.user" :ctx="ctx" :admin="app.admin" />
-    <FilesPage v-if="page==='status'" :ctx="ctx" />
-    <div data-page="background" v-show="page==='background'">
-     <BackgroundPanel v-if="backgroundEnabled && app" ref="background" :key="app.user" :ctx="ctx" />
-    </div>
+ <AppShell app-root v-model="page" :ctx="ctx" :locale="ctx.locale" :pages="pages" :description="subtitle" :denied="signIn" sidebar-storage-key="__PACKAGE__">
+  <template #denied><LoginPage :session="login" :locale="ctx.locale" /></template>
+  <template #actions><Button variant="secondary" :disabled="busy" @click="refreshAll">{{ copy.refresh }}</Button><Button v-if="login.enabled.value" variant="secondary" :disabled="busy" @click="signOut">{{ copy.signOut }}</Button></template>
+  <div class="integration-app" :aria-busy="busy" :aria-label="copy.settings">
+   <Callout v-if="error" tone="danger" :title="copy.actionRequired"><span role="alert">{{ error }}</span></Callout>
+   <p v-if="notice" role="status">{{ notice }}</p>
+   <div data-page="status" v-show="page==='status'">
+    <SettingsSection :title="copy.statusTitle" :collapsible="false" :loading="busy && !app">
+     <p v-if="app">{{ app.package }} · {{ app.user }} · {{ app.version }}</p>
+     <p v-else-if="error" role="status">{{ copy.statusError }}</p>
+    </SettingsSection>
+    <PortalSettings v-if="ctx.portal && app" :key="portalKey" :portal="ctx.portal" />
+    <SettingsSection v-if="app?.admin" :title="copy.greeting" :collapsible="false">
+     <Form direction="vertical" @submit.prevent="save"><FormItem :label="copy.greeting"><Textarea v-model="text" :disabled="busy" /></FormItem>
+      <FormActions><Button variant="primary" :disabled="busy || !text.trim()" @click="save">{{ copy.save }}</Button></FormActions>
+     </Form>
+    </SettingsSection>
    </div>
-  </AppShell>
-  </ConfigProvider>
- </AppRoot>
+   <CapabilityPanels v-if="app" ref="panels" :key="app.user" :ctx="ctx" :admin="app.admin" />
+   <FilesPage v-if="page==='status'" :ctx="ctx" />
+   <div data-page="background" v-show="page==='background'">
+    <BackgroundPanel v-if="backgroundEnabled && app" ref="background" :key="app.user" :ctx="ctx" />
+   </div>
+  </div>
+ </AppShell>
 </template>

package/templates/native-go-vue/frontend/test/apps.test.ts

@@ -2,7 +2,8 @@
 import {expect,test,vi} from 'vitest'
 import {nextTick} from 'vue'
 import {mount} from '../src/main'
-import type {Context} from '@synopackageland/sdk'
+import {createStandaloneContext, type Context} from '@synopackageland/sdk'
+import {dsmWindow} from './context'
 async function settle(){for(let i=0;i<16;i++){await Promise.resolve();await nextTick()}}
 function fixture(id:string){
  const reopen:Array<()=>void>=[]
@@ -12,7 +13,7 @@ function fixture(id:string){
   if(method==='greeting.set')return {}
   throw {code:'unknown_method'}
  })
- const ctx={locale:'en',call,reopen(fn:()=>void){reopen.push(fn);return ()=>{}}} as Context
+ const ctx=dsmWindow({call,reopen(fn:()=>void){reopen.push(fn);return ()=>{}}})
  const root=document.createElement('div');document.body.append(root)
  const app=mount(root,ctx)
  return {root,app,call,reopen,ctx,close(){app.unmount();root.remove()}}
@@ -78,7 +79,7 @@ test('the app renders and loads status while the session check is still pending'
   if(method==='greeting.get')return {text:'Hello Eager'}
   throw {code:'unknown_method'}
  })
- const ctx={locale:'en',call,reopen(){return ()=>{}}} as unknown as Context
+ const ctx=dsmWindow({call})
  const root=document.createElement('div');document.body.append(root)
  const app=mount(root,ctx)
  try{
@@ -99,7 +100,7 @@ test('a status request that raced the session check is retried once the session
   if(method==='greeting.get')return {text:'Hello Raced'}
   throw {code:'unknown_method'}
  })
- const ctx={locale:'en',call,reopen(){return ()=>{}}} as unknown as Context
+ const ctx=dsmWindow({call})
  const root=document.createElement('div');document.body.append(root)
  const app=mount(root,ctx)
  try{
@@ -108,13 +109,14 @@ test('a status request that raced the session check is retried once the session
   expect(root.textContent).toContain('Raced · admin · 1')
  }finally{app.unmount();root.remove()}
 })
-function hosted(host?:'dsm'|'standalone-web'){
+function hosted(host:'dsm'|'standalone-web'){
  const call=vi.fn(async(method:string)=>{
   if(method==='app.status')return {package:'Hosted',version:'1',user:'admin',admin:false}
   throw {code:'unknown_method'}
  })
- const activateWindow=vi.fn(()=>({status:'requested'}))
- const ctx={locale:'en',call,reopen(){return ()=>{}},...(host?{host:{platform:()=>({host}),activateWindow}}:{})} as unknown as Context
+ // Outside DSM the App owns the page.
+ const ctx=host==='dsm'?dsmWindow({call}):createStandaloneContext({call})
+ const activateWindow=ctx.host.activateWindow
  const root=document.createElement('div');document.body.append(root)
  const app=mount(root,ctx)
  return {activateWindow,close(){app.unmount();root.remove()}}
@@ -140,10 +142,8 @@ test('on a narrow viewport the floating dialogs become sheets that stay on scree
  }finally{f.close();Object.defineProperty(window,'innerWidth',{configurable:true,value:width})}
 })
 test('outside a DSM window dialogs stay inside the app',async()=>{
- for(const host of [undefined,'standalone-web'] as const){
-  const f=hosted(host)
-  try{await settle();expect(document.querySelector('[data-ui-floating]')).toBeNull()}finally{f.close()}
- }
+ const f=hosted('standalone-web')
+ try{await settle();expect(document.querySelector('[data-ui-floating]')).toBeNull()}finally{f.close()}
 })
 test('the status page follows the UI layout rules',async()=>{
  let answer:(value:unknown)=>void=()=>{}
@@ -153,7 +153,7 @@ test('the status page follows the UI layout rules',async()=>{
   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)
+ const app=mount(root,dsmWindow({call}))
  try{
   await settle()
   // A loading section keeps its title and shows a skeleton, not a sentence.
@@ -166,3 +166,56 @@ test('the status page follows the UI layout rules',async()=>{
   expect(root.querySelector('textarea')!.closest('[data-form-item]')!.getAttribute('data-direction')).toBe('vertical')
  }finally{app.unmount();root.remove()}
 })
+test('a code the bridge runtime adds shows the SDK text in the DSM language',async()=>{
+ const f=fixture('Bridge')
+ try{
+  await settle();f.call.mockRejectedValue({code:'app_unavailable'});f.reopen.forEach(fn=>fn());await settle()
+  expect(f.root.textContent).toContain('The App is not available right now. Try again later.')
+ }finally{f.close()}
+})
+test('a Portal or standalone launch lays the App out full-page; a DSM window keeps the window layout',async()=>{
+ // jsdom lays nothing out: give every element a wide desktop width.
+ const box=vi.spyOn(HTMLElement.prototype,'getBoundingClientRect').mockReturnValue({width:1400,height:800} as DOMRect)
+ const viewport=()=>document.head.querySelector('meta[name="viewport"]')
+ const window=fixture('Window')
+ const call=vi.fn(async(method:string)=>method==='app.status'?{package:'Page',version:'1',user:'alice',admin:false}:{})
+ const ctx=createStandaloneContext({call,displayName:'Page App',appIcon:'webman/3rdparty/Page/images/icon_64.png',user:{name:'alice',isAdmin:false}})
+ const root=document.createElement('div');document.body.append(root)
+ try{
+  await settle()
+  expect(window.root.querySelector('[data-ui-layout-mode]')?.getAttribute('data-ui-layout-mode')).toBe('window')
+  expect(viewport()).toBeNull()
+  // A DSM window has DSM's own title bar and account: the sidebar shows no user.
+  expect(window.root.querySelector('[data-ui-sidebar-footer]')).toBeNull()
+  const app=mount(root,ctx);await settle()
+  expect(root.querySelector('[data-ui-layout-mode]')?.getAttribute('data-ui-layout-mode')).toBe('web')
+  // DSM's page has no device-width viewport, so a phone would never reach the mobile layout.
+  expect(viewport()?.getAttribute('content')).toContain('width=device-width')
+  const brand=root.querySelector('[data-ui-sidebar-brand]')
+  expect(brand?.textContent).toContain('Page App')
+  expect(brand?.querySelector('img')?.getAttribute('src')).toBe('webman/3rdparty/Page/images/icon_64.png')
+  // The signed-in DSM account and its role, from ctx.user.
+  expect(root.querySelector('[data-ui-sidebar-footer]')?.textContent).toContain('alice')
+  expect(root.querySelector('[data-ui-sidebar-footer]')?.textContent).toContain('DSM user')
+  app.unmount()
+  expect(viewport()).toBeNull()
+ }finally{window.close();root.remove();box.mockRestore()}
+})
+test('a needed sign-in takes the shell page in place of the App pages, inside the App root',async()=>{
+ const call=vi.fn(async(method:string)=>{
+  if(method==='identity.status')return {enabled:true}
+  if(method==='identity.session')return {user:'alice',uid:'1',expiresAt:new Date(Date.now()-1000).toISOString()}
+  throw {code:'session_required'}
+ })
+ const root=document.createElement('div');document.body.append(root)
+ const app=mount(root,dsmWindow({call}))
+ try{
+  await settle()
+  const form=root.querySelector('form')
+  expect(form).not.toBeNull()
+  // The shell lays the sign-in page out as one of its pages: no sidebar, the page body's padding.
+  expect(form!.closest('[data-page-content-body]')).not.toBeNull()
+  expect(root.querySelector('nav')).toBeNull()
+  expect(form!.closest('[data-ui-app]')).not.toBeNull()
+ }finally{app.unmount();root.remove()}
+})

package/templates/native-go-vue/frontend/test/context.ts

@@ -0,0 +1,8 @@
+import {vi} from 'vitest'
+import {createStandaloneContext, createStandaloneHost, type Context} from '@synopackageland/sdk'
+/** The ctx the CLI gives a DSM desktop window; activateWindow is a spy. */
+export function dsmWindow(fields: Pick<Context, 'call'> & Partial<Omit<Context, 'call'>>): Context {
+ const host = createStandaloneHost({host: 'dsm', dsmStandalone: false})
+ vi.spyOn(host, 'activateWindow')
+ return createStandaloneContext({fullPage: false, host, ...fields})
+}

package/templates/native-go-vue/frontend/test/native-controls.test.ts

@@ -18,10 +18,9 @@ test('FormItem labels sit above their controls and the UI binds the control id',
  expect(items.filter(file=>/<Form(?![^>]*direction="vertical")[\s>]|field\.controlId|#default="\{field\}"/.test(template(file)))).toEqual([])
 })
 // UI built-in text follows the Provider locale (nine locales), so every app root sets it once and no
-// component repeats a per-control locale or download label.
+// component repeats a per-control locale or download label. AppShell's app-root sets it from its locale.
 test('app roots set the UI locale once and components do not translate UI text themselves',()=>{
- const roots=sources(root).filter(file=>uses(file,'AppRoot'))
- expect(roots.length).toBeGreaterThan(0)
- expect(roots.filter(file=>!uses(file,'ConfigProvider'))).toEqual([])
+ expect(sources(root).filter(file=>/<AppShell[^>]*\sapp-root[\s>]/.test(template(file))).length).toBeGreaterThan(0)
+ expect(sources(root).filter(file=>uses(file,'AppRoot')&&!uses(file,'ConfigProvider'))).toEqual([])
  expect(sources(root).filter(file=>/download-label|external-label|<FilePicker[^>]*:locale=/.test(template(file)))).toEqual([])
 })

package/templates/native-go-vue/frontend/test/shell-i18n.test.ts

@@ -3,13 +3,13 @@
 import {expect,test,vi} from 'vitest'
 import {nextTick} from 'vue'
 import {mount} from '../src/main'
-import type {Context} from '@synopackageland/sdk'
+import {dsmWindow} from './context'
 import {appCopy} from '../src/i18n'
 import {identityCopy} from '@synopackageland/sdk/vue'
 async function settle(){for(let i=0;i<20;i++){await Promise.resolve();await nextTick()}}
 const buttons=(root:HTMLElement)=>[...root.querySelectorAll('button')].map(b=>b.textContent?.trim())
 function start(locale:string,call:(method:string)=>Promise<unknown>){
- const ctx={locale,call:vi.fn(call),reopen(){return ()=>{}}} as unknown as Context
+ const ctx=dsmWindow({locale,call:vi.fn(call) as never})
  const root=document.createElement('div');document.body.append(root)
  const app=mount(root,ctx)
  return {root,close(){app.unmount();root.remove()}}

package/templates/native-node/README.md

@@ -0,0 +1,153 @@
+# __DISPLAY_NAME__
+
+A native DSM package (`__PACKAGE__`): a Node.js App behind the SDK's runtime,
+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   (the SDK runtime, runs as package user)
+      1. transport guards: POST, JSON, same origin, ≤ 1 MiB, bounded JSON complexity
+      2. one DSM authentication, the entry gate and app/permissions.json
+      3. DSM's Node.js v20 package runs `backend/app/main.js` once per call
+      4. your method, which may ask the runtime for services (files, jobs, executor)
+```
+
+## Quick start
+
+Needs Node.js 20 or later with `synopkgland` installed. The SPK depends on DSM's **Node.js v20** package (INFO `install_dep_packages`).
+
+```bash
+(cd backend && npm ci && npm test && npm run build)   # method tests, then app/*.js
+synopkgland build           # → dist/__PACKAGE__-0.1.0-0001-{x86_64,aarch64}.spk
+synopkgland inspect dist/__PACKAGE__-0.1.0-0001-x86_64.spk
+```
+
+Run `npm run build` in `backend` before every `synopkgland check` or `build`: the SPK ships the compiled `backend/app`.
+
+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.
+
+## 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 |
+| `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/routes.ts` | Your methods: `build` registers them | Yes — your backend |
+| `backend/src/jobs.ts`, `root-ops.ts`, `delegate.ts` | Capability examples (stubs unless `init --with` added them) | Yes |
+| `backend/src/main.ts` | Runs the App on the runtime's channel | Rarely |
+| `backend/app/` | `npm run build` output (`*.js`, ignored by git), `package.json` and `permissions.json`: the directory the SPK ships | Only `permissions.json` |
+| `backend/test/` | node:test tests; `call` plays the runtime | Yes |
+| `backend/package.json`, `package-lock.json` | TypeScript (NodeNext) and the Node SDK `@synopackageland/app` from `backend/vendor`, which `synopkgland init` copies from the SDK release | Dependencies |
+| `dist/` | Built SPKs (ignored by git) | No |
+
+`build` generates everything else: `INFO`, `conf/privilege`
+(`run-as: package`), lifecycle scripts, icons, the DSM window wrapper and the
+runtime CGI at `ui/cgi/api.cgi`.
+
+## Add a method
+
+Register it in `build`. Every method defaults to DSM administrator membership;
+all access rules live in `backend/app/permissions.json`:
+
+```ts
+export function build(cfg: Config): App {
+  const app = new App()
+  ...
+  app.method('notes.list', (ctx, params) => listNotes(cfg, ctx, params)) // new: administrators by default
+  return app
+}
+
+function listNotes(cfg: Config, ctx: Context, params: unknown) {
+  const { folder } = strings(params, 'folder') // anything else is bad_request
+  return { owner: ctx.user, folder, notes: [] }
+}
+```
+
+Add a test to `backend/test/` with `call(app, 'notes.list', { folder: 'work' }, { services })`. Call it from the UI with `ctx.call("notes.list", { folder: "work" })`.
+
+Throw `new AppError(code, message)` (or `AppError.badRequest(message)`) for an error the browser may see; anything else is `internal`, with the stack in the package's log. Call runtime services through `service()` in `src/service.ts`: it passes the runtime's refusals on to the browser.
+
+The runtime refuses before your App runs: `session_required`, `admin_required`,
+`unknown_method`, `request_timeout` and the transport guards' codes. The UI
+shows `error.<code>` from its catalogs.
+
+### 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.
+
+| 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 |
+| method the App does not register | `session_required` | `unknown_method` | `unknown_method` |
+
+Missing or invalid JSON, duplicate keys, unknown permissions and rules for
+methods the App does not register fail closed. Changing policy requires
+rebuilding the SPK.
+
+## Capabilities
+
+`synopkgland init --with` adds examples that use the runtime's services through
+`ctx.runtime`; each comes with its tests:
+
+| `--with` | Methods | Runtime services |
+| --- | --- | --- |
+| `jobs` | `hash.submit`, `hash.get`, `hash.cancel` | `files.read` with the caller's session, `bg.submit`, `bg.get`, `bg.cancel` |
+| `root-ops` | `whoami.run` | `root.run` of `root/whoami.sh`, once an administrator approves the executor |
+| `delegate` | `report.save` | `delegate.move_from_staging` into a folder the caller chose |
+
+A service refuses with its own code (`limit_exceeded`, `read_failed`, the
+executor's refusals); the examples pass it on to the browser. `synopkgland add`
+works on Go backends only: start a Node.js App with the capabilities it needs.
+
+## The SDK
+
+`backend.sdk` in dsm-package.yaml names the SDK release: the build ships its runtime and its Node SDK as `backend/app/node_modules/@synopackageland/app`, and reads the method list from `main.js --describe`. `backend/vendor/@synopackageland/app` is the same SDK for tests and type checks; replace it with the new release's when you change `backend.sdk`. Upgrade the SDK by changing that version; `synopkgland check`
+refuses versions this CLI does not support. The bridge protocol, the services
+and their codes are documented in the SDK repository:
+<https://github.com/synopackageland/syno-pkg-land-sdk> (`spec/bridge/v1`).
+
+## UI and languages
+
+The UI is the same as the Go template's. `ui/app.js` registers
+`window.DsmPackageApps[<package>].mount(root, ctx)`; `ctx.call(method, params)`
+is the only transport and `ctx.t(key, values)` reads
+`i18n/messages/<locale>.json` (`en`, `zh-TW`, `zh-CN`, `ja`, `ko`, `de`,
+`fr`, `es`, `it`). Add `error.<code>` for every code your methods return.
+`synopkgland check` and `build` refuse a language file with missing or extra
+keys, a dropped `{placeholder}` or a listed message that drifts from the
+glossary. `--ui vue` gives the Vue shell in `frontend/` instead.
+
+## Data, upgrades, uninstall
+
+The App stores data in `/var/packages/__PACKAGE__/var` (`SYNOPKGLAND_DATA_DIR`,
+kept across upgrades). Bump `build` for every SPK you hand out and `version`
+for feature releases. Uninstalling keeps the data unless the administrator
+ticks **Also delete the app data listed above** in the uninstall wizard.
+
+## Support matrix
+
+| | Status |
+| --- | --- |
+| Build hosts | macOS, Linux |
+| Target CPUs | x86_64 and aarch64 DSM models (one SPK each); armv7 is opt-in in `arches`, built but not NAS-verified |
+| DSM | 7.1 or later declared (`os_min_ver`) |

package/templates/native-node/backend/app/package.json

@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "type": "module"
+}

package/templates/native-node/backend/app/permissions.json

@@ -0,0 +1,5 @@
+{
+  "schema": 1,
+  "default": "administrators",
+  "methods": {}
+}

package/templates/native-node/backend/package-lock.json

@@ -0,0 +1,59 @@
+{
+  "name": "backend",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "backend",
+      "dependencies": {
+        "@synopackageland/app": "file:vendor/@synopackageland/app"
+      },
+      "devDependencies": {
+        "@types/node": "18.19.130",
+        "typescript": "5.9.3"
+      }
+    },
+    "node_modules/@synopackageland/app": {
+      "resolved": "vendor/@synopackageland/app",
+      "link": true
+    },
+    "node_modules/@types/node": {
+      "version": "18.19.130",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.130.tgz",
+      "integrity": "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~5.26.4"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "5.26.5",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz",
+      "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "vendor/@synopackageland/app": {
+      "version": "0.0.0",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    }
+  }
+}

package/templates/native-node/backend/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "backend",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "rm -rf build && tsc && node --test build/test/*.test.js"
+  },
+  "dependencies": {
+    "@synopackageland/app": "file:vendor/@synopackageland/app"
+  },
+  "devDependencies": {
+    "@types/node": "18.19.130",
+    "typescript": "5.9.3"
+  }
+}

package/templates/native-node/backend/src/delegate.ts

@@ -0,0 +1,5 @@
+// Saves to a user's destination: `synopkgland init --with delegate` replaces this stub with an example.
+import type { App } from '@synopackageland/app'
+import type { Config } from './routes.js'
+
+export function register(_app: App, _cfg: Config): void {}

package/templates/native-node/backend/src/jobs.ts

@@ -0,0 +1,5 @@
+// Background jobs: `synopkgland init --with jobs` replaces this stub with an example.
+import type { App } from '@synopackageland/app'
+import type { Config } from './routes.js'
+
+export function register(_app: App, _cfg: Config): void {}

package/templates/native-node/backend/src/main.ts

@@ -0,0 +1,4 @@
+// The App: the runtime starts it once per call (spec/bridge/v1).
+import { build, configFromEnv } from './routes.js'
+
+await build(configFromEnv()).run()

package/templates/native-node/backend/src/params.ts

@@ -0,0 +1,11 @@
+// Request params, checked strictly: the browser sends what it likes.
+import { AppError } from '@synopackageland/app'
+
+/** params as an object with exactly these string fields, else bad_request. */
+export function strings<K extends string>(params: unknown, ...names: K[]): Record<K, string> {
+  const ok = typeof params === 'object' && params !== null && !Array.isArray(params)
+    && Object.keys(params).sort().join() === [...names].sort().join()
+    && names.every((name) => typeof (params as Record<string, unknown>)[name] === 'string')
+  if (!ok) throw AppError.badRequest(`params must be {${[...names].sort().join(', ')}}`)
+  return params as Record<K, string>
+}

package/templates/native-node/backend/src/root-ops.ts

@@ -0,0 +1,5 @@
+// Root operations: `synopkgland init --with root-ops` replaces this stub with an example.
+import type { App } from '@synopackageland/app'
+import type { Config } from './routes.js'
+
+export function register(_app: App, _cfg: Config): void {}