@synopackageland/templates 0.9.9 → 0.10.1

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

@@ -0,0 +1,35 @@
+// Saves to a user's destination: write a report and move it there.
+//
+// The browser picks the destination with the SDK's Background saves page and
+// sends its delegation ID; the executor checks that it is the caller's grant
+// and writes the file as the caller, never as root. A save that failed may be
+// repeated with the same job ID: the same file is sent again, and the executor
+// copies it at most once.
+import { mkdirSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { AppError, type App, type Context } from '@synopackageland/app'
+import { strings } from './params.js'
+import type { Config } from './routes.js'
+import { service } from './service.js'
+
+const JOB_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/
+
+export function register(app: App, cfg: Config): void {
+  app.method('report.save', (ctx, params) => save(cfg, ctx, params))
+}
+
+function save(cfg: Config, ctx: Context, params: unknown) {
+  const { delegation_id, job_id } = strings(params, 'delegation_id', 'job_id')
+  if (!JOB_ID.test(job_id)) throw AppError.badRequest("job_id must be 1 to 128 letters, digits, '.', '_' or '-'")
+  const name = `report-${job_id}.txt`
+  // The runtime's delegate service moves files from here.
+  const staging = join(cfg.dataDir, 'executor-staging')
+  mkdirSync(staging, { recursive: true, mode: 0o700 })
+  const path = join(staging, name)
+  try {
+    writeFileSync(path, `Report for ${ctx.user}, ${new Date().toISOString().replace(/\.\d+Z$/, 'Z')}\n`, { flag: 'wx', mode: 0o600 })
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e
+  }
+  return service(ctx, 'delegate.move_from_staging', { delegation_id, job_id, staging: name, name, size: statSync(path).size })
+}

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

@@ -0,0 +1,51 @@
+import assert from 'node:assert/strict'
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, test } from 'node:test'
+import { build, type Config } from '../src/routes.js'
+import { Refusal, call, type Services } from './support.js'
+
+const SAVED = { state: 'queued' }
+let cfg: Config
+let staging: string
+
+beforeEach(() => {
+  const root = mkdtempSync(join(tmpdir(), 'app-'))
+  cfg = { packageId: 'ExampleApp', dataDir: root, packagesRoot: root }
+  staging = join(root, 'executor-staging')
+})
+afterEach(() => rmSync(cfg.dataDir, { recursive: true, force: true }))
+
+const save = (user = 'alice', move: Services[string] = () => SAVED) =>
+  call(build(cfg), 'report.save', { delegation_id: 'd1', job_id: 'job-1' }, { user, admin: false, services: { 'delegate.move_from_staging': move } })
+
+test('report.save moves a private report to the caller\'s destination', async () => {
+  const reply = await save()
+  assert.deepEqual(reply.data, SAVED)
+  const path = join(staging, 'report-job-1.txt')
+  assert.match(readFileSync(path, 'utf8'), /alice/)
+  assert.equal(statSync(path).mode & 0o777, 0o600)
+  const move = { delegation_id: 'd1', job_id: 'job-1', staging: 'report-job-1.txt', name: 'report-job-1.txt', size: statSync(path).size }
+  assert.deepEqual(reply.services, [['delegate.move_from_staging', move]])
+})
+
+test('a repeated report.save sends the same file again', async () => {
+  const first = (await save()).services
+  const report = readFileSync(join(staging, 'report-job-1.txt'), 'utf8')
+  assert.deepEqual((await save('bob')).services, first)
+  assert.equal(readFileSync(join(staging, 'report-job-1.txt'), 'utf8'), report)
+})
+
+test('report.save passes on the executor\'s refusal', async () => {
+  const reply = await save('alice', () => { throw new Refusal('DELEGATION_DENIED', 'The destination is no longer allowed.') })
+  assert.equal(reply.error?.code, 'DELEGATION_DENIED')
+})
+
+test('report.save refuses invalid params before writing', async () => {
+  for (const params of [null, { delegation_id: 'd1' }, { delegation_id: 'd1', job_id: '../x' }, { delegation_id: 'd1', job_id: '' }, { delegation_id: 1, job_id: 'j' }]) {
+    const reply = await call(build(cfg), 'report.save', params)
+    assert.deepEqual([reply.error?.code, reply.services], ['bad_request', []], JSON.stringify(params))
+  }
+  assert.equal(existsSync(staging), false)
+})

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

@@ -0,0 +1,38 @@
+// Background jobs: hash a NAS file the caller may read.
+//
+// The SDK's worker runs each job as the package account: it hashes the job's
+// input (SHA-256) and keeps the result for the job's owner, the caller. The
+// runtime serves files.read with the caller's DSM session and bg.* for the
+// caller's own jobs only.
+import { copyFileSync, mkdirSync, unlinkSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { basename, join } from 'node:path'
+import { AppError, type App, type Context } from '@synopackageland/app'
+import { strings } from './params.js'
+import type { Config } from './routes.js'
+import { service } from './service.js'
+
+/** A job's input is at most 512 KiB, copied into the job when it is submitted. */
+const MAX_INPUT = 512 * 1024
+
+export function register(app: App, cfg: Config): void {
+  app.method('hash.submit', (ctx, params) => submit(cfg, ctx, params))
+  app.method('hash.get', (ctx, params) => service(ctx, 'bg.get', strings(params, 'id')))
+  app.method('hash.cancel', (ctx, params) => service(ctx, 'bg.cancel', strings(params, 'id')))
+}
+
+async function submit(cfg: Config, ctx: Context, params: unknown) {
+  const { key, path } = strings(params, 'key', 'path')
+  const read = await service<{ path: string; size: number }>(ctx, 'files.read', { path })
+  if (read.size > MAX_INPUT) throw new AppError('limit_exceeded', 'The file is larger than allowed.')
+  // bg.submit takes its input from the data directory; the call's spool is elsewhere.
+  const inputs = join(cfg.dataDir, 'hash-inputs')
+  mkdirSync(inputs, { recursive: true, mode: 0o700 })
+  const input = join(inputs, randomUUID())
+  copyFileSync(read.path, input)
+  try {
+    return await service(ctx, 'bg.submit', { key, name: basename(path), input })
+  } finally {
+    unlinkSync(input)
+  }
+}

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

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, sep } from 'node:path'
+import { afterEach, beforeEach, test } from 'node:test'
+import { build, type Config } from '../src/routes.js'
+import { Refusal, call } from './support.js'
+
+const JOB = { job: { id: 'j1', state: 'queued' }, duplicate: false }
+let root: string
+let cfg: Config
+let submitted: Record<string, unknown>[]
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'app-'))
+  cfg = { packageId: 'ExampleApp', dataDir: join(root, 'var'), packagesRoot: join(root, 'packages') }
+  mkdirSync(cfg.dataDir)
+  submitted = []
+})
+afterEach(() => rmSync(root, { recursive: true, force: true }))
+
+function spool(content: Buffer) {
+  const path = join(root, 'spool')
+  writeFileSync(path, content)
+  return { path, size: content.length }
+}
+
+// The runtime reads the input file while it answers bg.submit.
+function submit(params: unknown) {
+  const p = params as { input: string }
+  submitted.push({ ...p, content: readFileSync(p.input, 'utf8') })
+  return JOB
+}
+
+test('hash.submit hashes a copy of the caller\'s file', async () => {
+  const services = { 'files.read': () => spool(Buffer.from('hello')), 'bg.submit': submit }
+  const reply = await call(build(cfg), 'hash.submit', { key: 'k1', path: '/home/report.txt' }, { services })
+  assert.deepEqual(reply.data, JOB)
+  assert.deepEqual(reply.services.map(([op]) => op), ['files.read', 'bg.submit'])
+  assert.deepEqual(reply.services[0]![1], { path: '/home/report.txt' })
+  const [job] = submitted as [{ key: string; name: string; content: string; input: string }]
+  assert.deepEqual([job.key, job.name, job.content], ['k1', 'report.txt', 'hello'])
+  assert.ok(job.input.startsWith(cfg.dataDir + sep), job.input)
+  assert.equal(existsSync(job.input), false, 'the copy is removed once submitted')
+})
+
+test('hash.submit refuses a file over the job input limit', async () => {
+  const services = { 'files.read': () => spool(Buffer.alloc(512 * 1024 + 1)), 'bg.submit': submit }
+  const reply = await call(build(cfg), 'hash.submit', { key: 'k1', path: '/home/big.bin' }, { services })
+  assert.equal(reply.error?.code, 'limit_exceeded')
+  assert.deepEqual(submitted, [])
+})
+
+test('hash.submit passes on the runtime\'s refusal', async () => {
+  const services = { 'files.read': () => { throw new Refusal('read_failed', 'Unable to read the file.') } }
+  const reply = await call(build(cfg), 'hash.submit', { key: 'k1', path: '/home/a' }, { services })
+  assert.equal(reply.error?.code, 'read_failed')
+})
+
+test('hash.submit refuses invalid params before any service', async () => {
+  for (const params of [null, { key: 'k1' }, { key: 1, path: '/home/a' }, { key: 'k1', path: '/home/a', x: 1 }]) {
+    const reply = await call(build(cfg), 'hash.submit', params)
+    assert.deepEqual([reply.error?.code, reply.services], ['bad_request', []], JSON.stringify(params))
+  }
+})
+
+test('hash.get and hash.cancel act on the caller\'s job', async () => {
+  for (const [method, op] of [['hash.get', 'bg.get'], ['hash.cancel', 'bg.cancel']] as const) {
+    const reply = await call(build(cfg), method, { id: 'j1' }, { services: { [op]: () => JOB.job } })
+    assert.deepEqual([reply.data, reply.services], [JOB.job, [[op, { id: 'j1' }]]])
+    assert.equal((await call(build(cfg), method, {})).error?.code, 'bad_request')
+  }
+})

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

@@ -0,0 +1,16 @@
+// Root operations: run root/whoami.sh as root.
+//
+// The executor runs only the root programs an administrator approved, and
+// checks the caller's DSM session and Application Privileges itself; the App
+// names the program and never runs anything as root.
+import { AppError, type App } from '@synopackageland/app'
+import type { Config } from './routes.js'
+import { service } from './service.js'
+
+export function register(app: App, _cfg: Config): void {
+  app.method('whoami.run', (ctx, params) => {
+    const none = params === null || (typeof params === 'object' && !Array.isArray(params) && Object.keys(params).length === 0)
+    if (!none) throw AppError.badRequest('whoami.run takes no params')
+    return service(ctx, 'root.run', { name: 'whoami' })
+  })
+}

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

@@ -0,0 +1,23 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { build, type Config } from '../src/routes.js'
+import { Refusal, call } from './support.js'
+
+const cfg: Config = { packageId: 'ExampleApp', dataDir: '/nonexistent', packagesRoot: '/nonexistent' }
+
+test('whoami.run runs the approved root program', async () => {
+  const output = { exit_code: 0, stdout: '0\n', stderr: '' }
+  for (const params of [null, {}]) {
+    const reply = await call(build(cfg), 'whoami.run', params, { services: { 'root.run': () => output } })
+    assert.deepEqual([reply.data, reply.services], [output, [['root.run', { name: 'whoami' }]]])
+  }
+})
+
+test('whoami.run passes on the executor\'s refusal', async () => {
+  const services = { 'root.run': () => { throw new Refusal('EXECUTOR_PAUSED', 'The executor is paused.') } }
+  assert.equal((await call(build(cfg), 'whoami.run', {}, { services })).error?.code, 'EXECUTOR_PAUSED')
+})
+
+test('whoami.run takes no params', async () => {
+  assert.equal((await call(build(cfg), 'whoami.run', { name: 'other' })).error?.code, 'bad_request')
+})

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

@@ -0,0 +1,56 @@
+# Native Node.js with Vue
+
+The Vue shell is the same as the Go template's. 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 `backend.sdk` in dsm-package.yaml. 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`. Errors show the app's own `frontend/src/i18n` text, or the SDK's
+`bridgeErrorCopy` for the codes the bridge runtime adds (`app_unavailable`
+and the services' refusals). Each window has its own Vue mount, request state
+and host subscriptions; unmount disposes subscriptions and ignores late responses.
+
+The `--with jobs`, `root-ops` and `delegate` examples add their methods to
+the Node.js App; the shell's panels call them with `ctx.call`. The SDK's
+background-jobs page and executor settings call the runtime's own browser
+methods (`bg.*`, `executor.*`); check the SDK release notes for the ones a
+bridge App's runtime serves.
+
+Use the installed `@synopackageland/ui`; package.json pins its version.
+`App.vue` lays the shell out with the SDK's `AppShell` (`@synopackageland/sdk/vue`):
+`pages` from `shellPages`, the header buttons in `#actions` and the pages in its
+default slot. Given `ctx`, it follows the launch. In a DSM desktop window it
+keeps `wide-layout="window"`, even maximized; the DSM host sets the 700px
+minimum window width. A Portal or standalone launch owns the whole page
+(`ctx.fullPage`, from the generated window): `AppShell` takes
+`wide-layout="web"` (the SaaS layout at 1200px or wider, mobile on a phone) and
+a device-width viewport, undone at unmount, since DSM's page has no
+device-width viewport. Its full-page sidebar names the App with
+`ctx.displayName` and `ctx.appIcon` (without them the page title and icon) and
+shows the signed-in DSM account and its role from `ctx.user`. See the ui's
+`docs/adaptive-layout.md`.
+`AppShell`'s `app-root` wraps it in an app-local `AppRoot` (app modal scope, on
+a full page as well, bounded at `height: 100%`) with the UI locale from
+`locale`; do not add another `AppRoot`.
+In a DSM window (not a full page) that `AppRoot` takes
+`dialog-bounds="viewport"`, so Dialogs can be dragged out of the window, and
+pressing one calls `ctx.host.activateWindow()` to bring the window to the
+front. Elsewhere Dialogs stay inside the App. A confirmed sign-in need sets
+`denied`: the `#denied` slot's `LoginPage` takes the place of the App's pages.
+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. 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.

package/templates/native-node-vue/gitignore

@@ -0,0 +1,4 @@
+dist/
+node_modules/
+backend/build/
+backend/app/*.js

package/templates/native-python/README.md

@@ -0,0 +1,150 @@
+# __DISPLAY_NAME__
+
+A native DSM package (`__PACKAGE__`): a Python 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 own Python 3 (3.8 or later) runs `backend/app/main.py` once per call
+      4. your method, which may ask the runtime for services (files, jobs, executor)
+```
+
+## Quick start
+
+Needs Node.js with `synopkgland` installed, and Python 3.8 or later.
+
+```bash
+(cd backend && python3 -m unittest discover -s tests)   # method tests
+synopkgland build           # → dist/__PACKAGE__-0.1.0-0001-{x86_64,aarch64}.spk
+synopkgland inspect dist/__PACKAGE__-0.1.0-0001-x86_64.spk
+```
+
+Install: Package Center → Settings → General → Trust Level "Any publisher",
+then Manual Install with the SPK for your NAS's CPU. Open
+**__DISPLAY_NAME__** from the DSM main menu: it shows who you are signed in
+as, what the backend reports, and (for administrators) a form that stores a
+greeting in the package's data folder.
+
+## 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/app/routes.py` | Your methods: `build` registers them | Yes — your backend |
+| `backend/app/jobs.py`, `root_ops.py`, `delegate.py` | Capability examples (stubs unless `init --with` added them) | Yes |
+| `backend/app/permissions.json` | Who may call each of your methods | Yes |
+| `backend/app/main.py` | Runs the App on the runtime's channel | Rarely |
+| `backend/tests/` | unittest tests; `support.call` plays the runtime | Yes |
+| `backend/vendor/synopkgland_app` | The Python SDK for tests, copied by `synopkgland init` from the SDK release; the build ships its own copy of the release `backend.sdk` names | No |
+| `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`:
+
+```python
+def build(cfg):
+    app = App()
+    ...
+    app.method("notes.list")(lambda ctx, params: list_notes(cfg, ctx, params))  # new: administrators by default
+    return app
+
+
+def list_notes(cfg, ctx, params):
+    p = fields(params, folder=str)  # anything else is bad_request
+    return {"owner": ctx.user, "notes": []}
+```
+
+Add a test to `backend/tests/` with `support.call(app, "notes.list", {"folder": "work"}, services={...})`. Call it from the UI with `ctx.call("notes.list", { folder: "work" })`.
+
+Raise `Error(code, message)` (or `Error.bad_request(message)`) for an error the browser may see; any other exception is `internal`, with the traceback in the package's log. A refusal from `ctx.runtime` is an `Error` too, so the browser sees the runtime's code.
+
+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 Python 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 Python SDK as `backend/app/vendor/synopkgland_app`, and reads the method list from `main.py --describe`. `backend/vendor/synopkgland_app` is the same SDK for tests; 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-python/backend/app/delegate.py

@@ -0,0 +1,5 @@
+"""Saves to a user's destination: `synopkgland init --with delegate` replaces this stub with an example."""
+
+
+def register(app, cfg):
+    pass

package/templates/native-python/backend/app/jobs.py

@@ -0,0 +1,5 @@
+"""Background jobs: `synopkgland init --with jobs` replaces this stub with an example."""
+
+
+def register(app, cfg):
+    pass

package/templates/native-python/backend/app/main.py

@@ -0,0 +1,5 @@
+"""The App: the runtime starts it once per call (spec/bridge/v1)."""
+
+import routes
+
+routes.build(routes.Config.from_env()).run()

package/templates/native-python/backend/app/params.py

@@ -0,0 +1,10 @@
+"""Request params, checked strictly: the browser sends what it likes."""
+
+from synopkgland_app import Error
+
+
+def fields(params, **types):
+    """params as an object with exactly these fields of these types, else bad_request."""
+    if not isinstance(params, dict) or set(params) != set(types) or not all(isinstance(params[k], t) for k, t in types.items()):
+        raise Error.bad_request("params must be {%s}" % ", ".join(sorted(types)))
+    return params

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

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

package/templates/native-python/backend/app/root_ops.py

@@ -0,0 +1,5 @@
+"""Root operations: `synopkgland init --with root-ops` replaces this stub with an example."""
+
+
+def register(app, cfg):
+    pass

package/templates/native-python/backend/app/routes.py

@@ -0,0 +1,107 @@
+"""The App's methods. Register a method in build() and give it a rule in
+permissions.json unless only administrators may call it: the runtime has
+checked the DSM session, the entry gate and that rule before a handler runs.
+"""
+
+import json
+import os
+import platform
+import sys
+import tempfile
+import time
+
+from synopkgland_app import App, Error
+
+import delegate
+import jobs
+import root_ops
+from params import fields
+
+
+class Config:
+    """Where the App's state lives; the runtime sets the environment."""
+
+    def __init__(self, package, data_dir, packages_root="/var/packages"):
+        self.package = package
+        # The package's own data directory (/var/packages/<package>/var), kept across upgrades.
+        self.data_dir = data_dir
+        self.packages_root = packages_root
+
+    @classmethod
+    def from_env(cls):
+        return cls(os.environ.get("SYNOPKGLAND_PACKAGE", ""), os.environ.get("SYNOPKGLAND_DATA_DIR", ""))
+
+
+def build(cfg):
+    app = App()
+    app.method("app.status")(lambda ctx, params: status(cfg, ctx))
+    app.method("greeting.get")(lambda ctx, params: get_greeting(cfg))
+    app.method("greeting.set")(lambda ctx, params: set_greeting(cfg, ctx, params))
+    # Each capability module is a stub until `synopkgland init --with` adds its example.
+    for capability in (jobs, root_ops, delegate):
+        capability.register(app, cfg)
+    return app
+
+
+def status(cfg, ctx):
+    result = {
+        "package": cfg.package,
+        "version": installed_version(cfg),
+        "user": ctx.user,
+        "admin": ctx.admin,
+        "process": {"uid": os.getuid(), "gid": os.getgid()},
+        "language": "Python " + platform.python_version(),
+        "platform": sys.platform + "/" + platform.machine(),
+        "time": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+    try:
+        # Served only when dsm-package.yaml declares a portal.
+        result["portal"] = ctx.runtime("portal.status")
+    except Error:
+        pass
+    return result
+
+
+def installed_version(cfg):
+    """The version in the package's INFO, or "" outside DSM."""
+    try:
+        with open(os.path.join(cfg.packages_root, cfg.package, "INFO"), encoding="utf-8") as info:
+            for line in info:
+                if line.startswith("version="):
+                    return line[len("version=") :].strip().strip('"')
+    except OSError:
+        pass
+    return ""
+
+
+def greeting_path(cfg):
+    return os.path.join(cfg.data_dir, "greeting.json")
+
+
+def get_greeting(cfg):
+    try:
+        with open(greeting_path(cfg), encoding="utf-8") as f:
+            return json.load(f)
+    except FileNotFoundError:
+        return {"text": "Hello"}
+
+
+def set_greeting(cfg, ctx, params):
+    text = fields(params, text=str)["text"]
+    if not 1 <= len(text) <= 200:
+        raise Error.bad_request("text must be 1 to 200 characters")
+    greeting = {"text": text, "updated_by": ctx.user}
+    write_file_atomic(greeting_path(cfg), json.dumps(greeting).encode())
+    return greeting
+
+
+def write_file_atomic(path, data):
+    """Replace path in one rename, so readers never see half a file."""
+    fd, tmp = tempfile.mkstemp(dir=os.path.dirname(path), prefix=".tmp-")
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+        os.replace(tmp, path)
+    except BaseException:
+        os.unlink(tmp)
+        raise