@synopackageland/templates 0.9.9 → 0.10.1

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 {}

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

@@ -0,0 +1,97 @@
+// The App's methods. Register a method in build() and give it a rule in
+// app/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 { randomUUID } from 'node:crypto'
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { App, AppError, type Context } from '@synopackageland/app'
+import * as delegate from './delegate.js'
+import * as jobs from './jobs.js'
+import { strings } from './params.js'
+import * as rootOps from './root-ops.js'
+
+/** Where the App's state lives; the runtime sets the environment. */
+export interface Config {
+  packageId: string
+  /** The package's own data directory (/var/packages/<package>/var), kept across upgrades. */
+  dataDir: string
+  packagesRoot: string
+}
+
+export function configFromEnv(): Config {
+  const env = process.env
+  return { packageId: env.SYNOPKGLAND_PACKAGE ?? '', dataDir: env.SYNOPKGLAND_DATA_DIR ?? '', packagesRoot: '/var/packages' }
+}
+
+export function build(cfg: Config): App {
+  const app = new App()
+  app.method('app.status', (ctx) => status(cfg, ctx))
+  app.method('greeting.get', () => getGreeting(cfg))
+  app.method('greeting.set', (ctx, params) => setGreeting(cfg, ctx, params))
+  // Each capability module is a stub until `synopkgland init --with` adds its example.
+  for (const capability of [jobs, rootOps, delegate]) capability.register(app, cfg)
+  return app
+}
+
+async function status(cfg: Config, ctx: Context) {
+  const result: Record<string, unknown> = {
+    package: cfg.packageId,
+    version: installedVersion(cfg),
+    user: ctx.user,
+    admin: ctx.admin,
+    process: { uid: process.getuid!(), gid: process.getgid!() },
+    language: `Node.js ${process.versions.node}`,
+    platform: `${process.platform}/${process.arch}`,
+    time: new Date().toISOString().replace(/\.\d+Z$/, 'Z'),
+  }
+  try {
+    // Served only when dsm-package.yaml declares a portal.
+    result.portal = await ctx.runtime('portal.status')
+  } catch {
+    // No portal.
+  }
+  return result
+}
+
+/** The version in the package's INFO, or "" outside DSM. */
+function installedVersion(cfg: Config): string {
+  try {
+    const info = readFileSync(join(cfg.packagesRoot, cfg.packageId, 'INFO'), 'utf8')
+    return /^version="?([^"\n]*)"?$/m.exec(info)?.[1] ?? ''
+  } catch {
+    return ''
+  }
+}
+
+const greetingPath = (cfg: Config) => join(cfg.dataDir, 'greeting.json')
+
+function getGreeting(cfg: Config): unknown {
+  try {
+    return JSON.parse(readFileSync(greetingPath(cfg), 'utf8'))
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return { text: 'Hello' }
+    throw e
+  }
+}
+
+function setGreeting(cfg: Config, ctx: Context, params: unknown) {
+  const { text } = strings(params, 'text')
+  const length = [...text].length
+  if (length < 1 || length > 200) throw AppError.badRequest('text must be 1 to 200 characters')
+  const greeting = { text, updated_by: ctx.user }
+  writeFileAtomic(greetingPath(cfg), JSON.stringify(greeting))
+  return greeting
+}
+
+/** Replaces path in one rename, so readers never see half a file. */
+export function writeFileAtomic(path: string, data: string): void {
+  const tmp = join(dirname(path), `.tmp-${randomUUID()}`)
+  try {
+    writeFileSync(tmp, data, { flag: 'wx' })
+    renameSync(tmp, path)
+  } catch (e) {
+    try { unlinkSync(tmp) } catch { /* never written */ }
+    throw e
+  }
+}

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

@@ -0,0 +1,22 @@
+// The runtime's services, with their refusals passed on to the browser.
+import { AppError, ServiceError, type Context } from '@synopackageland/app'
+
+/**
+ * ctx.runtime. A refusal the browser may see (limit_exceeded, read_failed,
+ * SCOPE_DENIED, ...) reaches it as the App's own error; any other code, such
+ * as the runtime's session_required, stays internal.
+ */
+export async function service<T>(ctx: Context, op: string, params: unknown = null): Promise<T> {
+  try {
+    return (await ctx.runtime(op, params)) as T
+  } catch (e) {
+    if (!(e instanceof ServiceError)) throw e
+    let passed: AppError
+    try {
+      passed = new AppError(e.code, e.message)
+    } catch {
+      throw e
+    }
+    throw passed
+  }
+}

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

@@ -0,0 +1,75 @@
+import assert from 'node:assert/strict'
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } 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 { call } from './support.js'
+
+let root: string
+let cfg: Config
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'app-'))
+  cfg = { packageId: 'ExampleApp', dataDir: join(root, 'var'), packagesRoot: join(root, 'packages') }
+  mkdirSync(cfg.dataDir)
+})
+afterEach(() => rmSync(root, { recursive: true, force: true }))
+
+function writeInfo(text: string) {
+  mkdirSync(join(cfg.packagesRoot, 'ExampleApp'), { recursive: true })
+  writeFileSync(join(cfg.packagesRoot, 'ExampleApp', 'INFO'), text)
+}
+
+test('app.status reports the caller and the installed version', async () => {
+  writeInfo('package="ExampleApp"\nversion="0.1.0-0001"\n')
+  const reply = await call(build(cfg), 'app.status', null, { user: 'alice', admin: false })
+  assert.equal(reply.ok, true, JSON.stringify(reply.error))
+  const status = reply.data
+  assert.deepEqual([status.package, status.version, status.user, status.admin], ['ExampleApp', '0.1.0-0001', 'alice', false])
+  assert.deepEqual(status.process, { uid: process.getuid!(), gid: process.getgid!() })
+  assert.match(status.language, /^Node\.js \d+\./)
+  assert.match(status.platform, /^\w+\/\w+$/)
+  assert.match(status.time, /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$/)
+})
+
+test('app.status without INFO has no version', async () => {
+  assert.equal((await call(build(cfg), 'app.status')).data.version, '')
+})
+
+test('app.status shows the portal when the runtime offers it', async () => {
+  const portal = { enabled: true, alias: 'example' }
+  const reply = await call(build(cfg), 'app.status', null, { services: { 'portal.status': () => portal } })
+  assert.deepEqual(reply.data.portal, portal)
+  assert.deepEqual(reply.services, [['portal.status', null]])
+})
+
+test('app.status without a portal leaves it out', async () => {
+  const reply = await call(build(cfg), 'app.status')
+  assert.equal(reply.ok, true, JSON.stringify(reply.error))
+  assert.equal('portal' in reply.data, false)
+})
+
+test('greeting.get defaults to Hello', async () => {
+  assert.deepEqual((await call(build(cfg), 'greeting.get')).data, { text: 'Hello' })
+})
+
+test('greeting.set stores the text and who set it', async () => {
+  const app = build(cfg)
+  const reply = await call(app, 'greeting.set', { text: 'Hi 👋' }, { user: 'alice' })
+  assert.deepEqual(reply.data, { text: 'Hi 👋', updated_by: 'alice' })
+  assert.deepEqual((await call(app, 'greeting.get')).data, { text: 'Hi 👋', updated_by: 'alice' })
+  assert.deepEqual(readdirSync(cfg.dataDir), ['greeting.json'])
+})
+
+test('greeting.set counts characters, not UTF-16 units', async () => {
+  assert.equal((await call(build(cfg), 'greeting.set', { text: '👋'.repeat(200) })).ok, true)
+})
+
+test('greeting.set refuses invalid params and keeps the old text', async () => {
+  for (const params of [null, [], {}, { text: '' }, { text: 'x'.repeat(201) }, { text: 5 }, { text: 'hi', extra: 1 }]) {
+    const reply = await call(build(cfg), 'greeting.set', params)
+    assert.equal(reply.error?.code, 'bad_request', JSON.stringify(params))
+  }
+  assert.deepEqual(readdirSync(cfg.dataDir), [])
+})

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

@@ -0,0 +1,67 @@
+// Calls an App method the way the runtime does: over a channel, with the
+// hello, the call, the services the method asks for and its result.
+import { PassThrough } from 'node:stream'
+import { createInterface } from 'node:readline'
+import type { App } from '@synopackageland/app'
+
+/** A service's refusal: the runtime answers the svc with this code. */
+export class Refusal extends Error {
+  constructor(readonly code: string, message = code) {
+    super(message)
+  }
+}
+
+/** Each op the method may ask for: returns the result or throws a Refusal. An op it lacks is unknown_service. */
+export type Services = Record<string, (params: unknown) => unknown>
+
+export interface Reply {
+  ok: boolean
+  data?: any
+  error?: { code: string; message: string }
+  /** The services the method asked for, in order. */
+  services: [string, unknown][]
+}
+
+export interface Caller {
+  user?: string
+  admin?: boolean
+  services?: Services
+}
+
+export async function call(app: App, method: string, params: unknown = null, caller: Caller = {}): Promise<Reply> {
+  const { user = 'admin', admin = true, services = {} } = caller
+  const toApp = new PassThrough()
+  const fromApp = new PassThrough()
+  const serving = app.serve(toApp, fromApp)
+  const send = (frame: object) => toApp.write(JSON.stringify(frame) + '\n')
+  const lines = createInterface({ input: fromApp })[Symbol.asyncIterator]()
+  send({ t: 'hello', versions: [1] })
+  await lines.next()
+  const ctx = { user, admin, locale: 'en', request_id: '0'.repeat(32), deadline_ms: 30000 }
+  send({ t: 'call', id: '1', method, params, ctx })
+  const asked: [string, unknown][] = []
+  try {
+    for (let line = await lines.next(); !line.done; line = await lines.next()) {
+      const frame = JSON.parse(line.value)
+      if (frame.t === 'result') return { ok: frame.ok, data: frame.data, error: frame.error, services: asked }
+      asked.push([frame.op, frame.params])
+      send(await answer(services, frame))
+    }
+    throw new Error('the App ended the channel without a result')
+  } finally {
+    toApp.end()
+    await serving
+  }
+}
+
+async function answer(services: Services, frame: { id: string; op: string; params: unknown }): Promise<object> {
+  const reply = { t: 'svc_result', id: frame.id }
+  try {
+    const service = services[frame.op]
+    if (!service) throw new Refusal('unknown_service', `no service ${frame.op}`)
+    return { ...reply, ok: true, result: await service(frame.params) }
+  } catch (e) {
+    if (!(e instanceof Refusal)) throw e
+    return { ...reply, ok: false, error: { code: e.code, message: e.message } }
+  }
+}

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

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "app"
+  },
+  "include": ["src/**/*.ts"]
+}

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

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"],
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "rootDir": ".",
+    "outDir": "build"
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}

package/templates/native-node/dsm-package.yaml

@@ -0,0 +1,80 @@
+# Standalone native DSM package: an unsigned SPK that runs as its own package
+# `synopkgland build` reads this file.
+schema: 2
+
+# INFO.package: letters and digits, starting with a letter. It also names the
+# DSM app (SYNO.SDS.<package>) and the CGI URL /webman/3rdparty/<package>/.
+package: __PACKAGE__
+version: 0.1.0
+# Increase for every SPK you hand out with the same version (INFO 0.1.0-0001).
+build: 1
+displayname: __DISPLAY_NAME__
+description: A native DSM package with a Node.js backend and a DSM window UI.
+# Package Center and DSM window icon: a square PNG of at least 256x256, or a
+# folder of icon_<size>.png. Omit to use the SDK default icon.
+# icon: assets/icon.png
+maintainer: Your Name
+# Optional INFO/website metadata. Omit fields you do not need.
+# metadata:
+#   contact_email: you@example.com
+#   support_email: support@example.com
+#   homepage: https://example.com
+#   source_url: https://github.com/you/your-app
+#   issues_url: https://github.com/you/your-app/issues
+#   license: MIT
+#   long_description:
+#     en: |-
+#       Explain what the app does and how to use it.
+#     zh-TW: Translated description.
+#   changelog:          # text, or per-language like long_description
+#     en: |-
+#       - Most important change first. Omit to use Release notes.
+#     zh-TW: |-
+#       - Translated changes.
+#   screenshots: [https://example.com/screenshot.png]
+os_min_ver: "7.1-42661"
+
+# One SPK per architecture. Supported: x86_64, aarch64, armv7 (add it here to
+# build it; armv7 is built but not NAS-verified).
+arches: [x86_64, aarch64]
+
+# The SDK's Go runtime is the CGI: it checks the DSM session, the entry gate
+# and app/permissions.json, then runs `node main.js` in backend/app as the
+# package account, once per call, with Package Center's Node.js (node.package
+# becomes an install dependency). backend/src compiles to backend/app: run
+# `npm ci` and `npm run build` in backend before check and build. sdk is the
+# SDK release whose runtime and Node SDK (node_modules/@synopackageland/app)
+# the build ships; the build reads the methods from `main.js --describe`.
+backend:
+  runtime: node
+  dir: backend/app
+  entry: main.js
+  sdk: 0.10.1
+  node: { package: Node.js_v20 }
+
+ui:
+  # Static files served at /webman/3rdparty/<package>/app/. app.js and app.css
+  # are required; anything else (images, chunks) is copied as is.
+  dir: ui
+
+# UI languages: i18n/messages/<locale>.json for en, zh-TW, zh-CN, ja, ko, de,
+# fr, es and it (DSM's other languages fall back to English). build checks
+# that every language has the en.json keys and placeholders, and that the keys
+# listed in the glossary use DSM's own wording.
+i18n:
+  messages: i18n/messages
+  glossary: i18n/glossary.json
+  # Package Center text per language (INFO displayname_<lang>/description_<lang>).
+  # English comes from displayname/description above.
+  info:
+    zh-TW: { description: 以 Node.js 後端與 DSM 視窗介面打造的原生 DSM 套件。 }
+    zh-CN: { description: 以 Node.js 后端与 DSM 窗口界面构建的原生 DSM 套件。 }
+    ja: { description: Node.js バックエンドと DSM ウィンドウ UI を備えたネイティブ DSM パッケージ。 }
+    ko: { description: Node.js 백엔드와 DSM 창 UI를 갖춘 네이티브 DSM 패키지. }
+    de: { description: Ein natives DSM-Paket mit Node.js-Backend und DSM-Fenster-Oberfläche. }
+    fr: { description: Un paquet DSM natif avec un backend Node.js et une interface en fenêtre DSM. }
+    es: { description: Un paquete nativo de DSM con backend en Node.js e interfaz en ventana de DSM. }
+    it: { description: Un pacchetto DSM nativo con backend Node.js e interfaccia in una finestra DSM. }
+
+# Optional SDK capabilities; delegate/rootOps share administrator-approved executor setup.
+capabilities: {}

package/templates/native-node/gitignore

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