@synopackageland/cli 0.3.9 → 0.4.0

package/dist/standalone/spk.js

@@ -0,0 +1,205 @@
+import { createHash } from "node:crypto";
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, isAbsolute } from "node:path";
+import { infoArchValue } from "../build-spk/dsm-arch.js";
+import { writeDsmWindowIcons, writePackageCenterIcons } from "../build-spk/dsm-icons.js";
+import { renderNativePrivilege } from "../build-spk/native-lifecycle.js";
+import { createReproducibleTar } from "../build-spk/reproducible-archive.js";
+import { DSM_LANGS, LOCALES } from "./i18n.js";
+import { CGI_PAYLOAD_PATH, renderUiConfig, renderWindowScript, windowScriptName } from "./dsm-window.js";
+const FILE_MODE = 0o644;
+const EXEC_MODE = 0o755;
+const MAX_UI_BYTES = 64 * 1024 * 1024;
+export const LIFECYCLE_SCRIPTS = [
+    "preinst",
+    "postinst",
+    "preuninst",
+    "postuninst",
+    "preupgrade",
+    "postupgrade",
+    "start-stop-status",
+];
+export class StandaloneBuildError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[${code}] ${message}`);
+        this.code = code;
+    }
+}
+/**
+ * Packs an unsigned Standalone Package SPK. Nothing in it runs as root: the
+ * package account owns the payload, lifecycle scripts do nothing, and the
+ * only entry point is the CGI DSM runs behind its own login.
+ */
+export async function assembleStandaloneSpk(options) {
+    const { manifest } = options;
+    const staging = mkdtempSync(join(tmpdir(), "syno-standalone-spk-"));
+    try {
+        const uiRoot = join(staging, "package", "ui");
+        const appDir = join(uiRoot, "app");
+        copyUiTree(manifest.ui.dir, appDir);
+        const assetVersion = digestTree(appDir).slice(0, 12);
+        writeFile(join(uiRoot, "config"), renderUiConfig(manifest));
+        writeFile(join(uiRoot, windowScriptName(manifest)), renderWindowScript(manifest, assetVersion));
+        writeDsmWindowIcons(uiRoot);
+        const cgiTarget = join(staging, "package", CGI_PAYLOAD_PATH);
+        mkdirSync(dirname(cgiTarget), { recursive: true });
+        copyFileSync(options.cgiPath, cgiTarget);
+        chmodSync(cgiTarget, EXEC_MODE);
+        if (manifest.integration && !options.helper)
+            throw new StandaloneBuildError("HELPER_ARTIFACT_REQUIRED", "integration SPK 缺少已建置的 helper inventory。");
+        if (options.helper) {
+            const dir = join(staging, "package", "integration");
+            mkdirSync(dir, { recursive: true });
+            copyFileSync(options.helper.binary, join(dir, "helper"));
+            chmodSync(join(dir, "helper"), EXEC_MODE);
+            writeFile(join(dir, "inventory.json"), JSON.stringify(options.helper.inventory));
+            writeFile(join(dir, "workers.json"), JSON.stringify(options.helper.workers.map(({ id, digest }) => ({ id, digest }))));
+            mkdirSync(join(dir, "workers"));
+            for (const worker of options.helper.workers) {
+                writeFileSync(join(dir, "workers", worker.id), worker.bytes, { mode: FILE_MODE });
+            }
+        }
+        if (manifest.integration?.identity === "better-auth") {
+            const source = join(manifest.root, "node", "dist", "app.mjs");
+            const rel = relative(realpathSync(manifest.root), realpathSync(source));
+            if (rel.startsWith("..") || isAbsolute(rel) || !lstatSync(source).isFile() || lstatSync(source).size > 16 * 1024 * 1024)
+                throw new StandaloneBuildError("STANDALONE_IDENTITY_PAYLOAD_INVALID", "Better Auth bundle must be a bounded regular file inside the project.");
+            const target = join(staging, "package", "integration", "identity", "app.mjs");
+            mkdirSync(dirname(target), { recursive: true });
+            copyFileSync(source, target);
+            chmodSync(target, FILE_MODE);
+        }
+        const packageTgz = join(staging, "package.tgz");
+        await createReproducibleTar(join(staging, "package"), packageTgz, { gzip: true });
+        rmSync(join(staging, "package"), { recursive: true, force: true });
+        const checksum = createHash("md5").update(readFileSync(packageTgz)).digest("hex");
+        writeFile(join(staging, "INFO"), renderInfo(manifest, options.arch, checksum));
+        mkdirSync(join(staging, "conf"));
+        writeFile(join(staging, "conf", "privilege"), renderNativePrivilege());
+        mkdirSync(join(staging, "scripts"));
+        for (const name of LIFECYCLE_SCRIPTS) {
+            writeFile(join(staging, "scripts", name), renderScript(name, manifest), EXEC_MODE);
+        }
+        writePackageCenterIcons(staging);
+        mkdirSync(dirname(options.outputPath), { recursive: true });
+        await createReproducibleTar(staging, options.outputPath);
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+function writeFile(path, content, mode = FILE_MODE) {
+    writeFileSync(path, content, "utf8");
+    chmodSync(path, mode);
+}
+function quote(value) {
+    return `"${value}"`;
+}
+/** Manifest validation already refused quotes, backslashes and newlines. */
+function renderInfo(manifest, arch, checksum) {
+    const fields = [
+        ["package", manifest.package],
+        ["version", manifest.spkVersion],
+        ["displayname", manifest.displayname],
+        ["description", manifest.description],
+        ["maintainer", manifest.maintainer],
+        ["arch", infoArchValue(arch)],
+        ["os_min_ver", manifest.os_min_ver],
+        ["dsmuidir", "ui"],
+        ["dsmappname", `SYNO.SDS.${manifest.package}.Instance`],
+        ["thirdparty", "yes"],
+        ["startable", "yes"],
+        ["checksum", checksum],
+    ];
+    if (manifest.integration?.identity === "better-auth")
+        fields.push(["install_dep_packages", "Node.js_v22"]);
+    for (const locale of LOCALES) {
+        const text = manifest.i18n?.info[locale];
+        if (text?.displayname)
+            fields.push([`displayname_${DSM_LANGS[locale]}`, text.displayname]);
+        if (text?.description)
+            fields.push([`description_${DSM_LANGS[locale]}`, text.description]);
+    }
+    return fields.map(([key, value]) => `${key}=${quote(value)}\n`).join("");
+}
+/** No lifecycle work: the CGI needs nothing installed, started or cleaned up. */
+function renderScript(name, manifest) {
+    if (manifest.integration && ["preupgrade", "preuninst", "start-stop-status"].includes(name)) {
+        const check = `/var/packages/${manifest.package}/target/integration/helper check-stopped || {
+  echo 'Run the approved helper_teardown or helper_disable operation before stopping, upgrading or uninstalling.' >&2
+  exit 1
+}
+`;
+        if (name !== "start-stop-status")
+            return `#!/bin/sh\n${check}`;
+        return `#!/bin/sh
+case "$1" in
+  start|status) exit 0 ;;
+  stop)
+${check}    ;;
+  *) exit 1 ;;
+esac
+`;
+    }
+    if (name === "start-stop-status") {
+        return `#!/bin/sh
+case "$1" in
+  start|stop|status) exit 0 ;;
+  *) exit 1 ;;
+esac
+`;
+    }
+    return "#!/bin/sh\nexit 0\n";
+}
+function copyUiTree(source, target) {
+    for (const entry of ["app.js", "app.css"]) {
+        if (!existsSync(join(source, entry))) {
+            throw new StandaloneBuildError("STANDALONE_UI_ENTRY_MISSING", `UI 目錄缺少 ${entry}：${source}`);
+        }
+    }
+    let total = 0;
+    const walk = (from, to) => {
+        mkdirSync(to, { recursive: true });
+        chmodSync(to, EXEC_MODE);
+        for (const name of readdirSync(from).sort()) {
+            const src = join(from, name);
+            const stat = lstatSync(src);
+            if (stat.isSymbolicLink()) {
+                throw new StandaloneBuildError("STANDALONE_UI_SYMLINK", `UI 目錄不可含 symlink：${src}`);
+            }
+            if (stat.isDirectory()) {
+                walk(src, join(to, name));
+            }
+            else if (stat.isFile()) {
+                total += stat.size;
+                if (total > MAX_UI_BYTES) {
+                    throw new StandaloneBuildError("STANDALONE_UI_TOO_LARGE", "UI 目錄超過 64 MiB。");
+                }
+                copyFileSync(src, join(to, name));
+                chmodSync(join(to, name), FILE_MODE);
+            }
+            else {
+                throw new StandaloneBuildError("STANDALONE_UI_SPECIAL_FILE", `UI 目錄只可含一般檔案與目錄：${src}`);
+            }
+        }
+    };
+    walk(source, target);
+}
+function digestTree(root) {
+    const hash = createHash("sha256");
+    const walk = (dir, prefix) => {
+        for (const name of readdirSync(dir).sort()) {
+            const path = join(dir, name);
+            if (lstatSync(path).isDirectory()) {
+                walk(path, `${prefix}${name}/`);
+            }
+            else {
+                hash.update(`${prefix}${name}\0`).update(readFileSync(path));
+            }
+        }
+    };
+    walk(root, "");
+    return hash.digest("hex");
+}

package/dist/templates/binary/synology-app.yaml

@@ -0,0 +1,7 @@
+schema: 1
+package: com.example.binary-app
+version: 0.1.0
+displayname: Binary App
+description: A minimal Syno Package Land app that runs one prebuilt binary.
+maintainer: Syno Package Land
+os_min_ver: "7.2-60000"

package/dist/templates/hello-files/compose.yaml

@@ -3,7 +3,6 @@ services:
     image: alpine:3.20
     command: ["sleep", "infinity"]
     volumes:
-      # Dynamic Shared Folder plus writable /state is Broker-managed and is
       # intentionally outside the zero-config docker-project resource-worker path.
       - "${MEDIA_SHARE}/data:/data:ro"
       - "${SYNOPKG_PKGVAR}/state:/state"

package/dist/templates/hello-web/compose.yaml

@@ -1,16 +1,19 @@
 services:
   web:
     image: busybox:1.36
-    # 兩個平台限制，改動前先看 docs/impl/STATUS.md 的 2026-08-24 段：
-    # 1) command／entrypoint 陣列不得有純數字元素（例如 "18333"）。DSM 的
-    #    docker-project worker 會在 YAML round-trip 時掉引號、把它變成整數，
-    #    postinst acquire 直接失敗（error 276 → 套件 broken/150，且 worker_msg
-    #    為空，開發者看不到原因）。所以 port 要包在單一字串裡。
-    #    `synopkgland validate` 已會擋這個寫法。
-    # 2) 預設不用 8080：那個 port 在真實 NAS 上很常被既有容器占用，而 port
-    #    衝突同樣以那個看不出原因的 broken/150 呈現。
-    # 官方 nginx image 也不能用：resource worker 注入任意 package UID/GID，
-    # nginx entrypoint 啟動階段需要 root，會在該身分下直接退出。
+    # DSM worker constraints to preserve when changing this service:
+    # 1) command/entrypoint arrays must not contain bare numeric elements
+    #    (such as "18333"). DSM's docker-project worker drops the quotes on a
+    #    YAML round-trip and turns them into integers, so postinst acquire
+    #    fails (error 276 -> package broken/150, with an empty worker_msg that
+    #    tells the developer nothing). Keep the port inside one string.
+    #    `synopkgland validate` already rejects the bare form.
+    # 2) The default is not 8080: that port is often taken by an existing
+    #    container on a real NAS, and the conflict shows up as the same
+    #    unexplained broken/150.
+    # The official nginx image cannot be used either: the resource worker
+    # injects an arbitrary package UID/GID, and the nginx entrypoint needs
+    # root during startup, so it exits immediately under that identity.
     command: ["sh","-c","httpd -f -p 18333 -h /usr/share/nginx/html"]
     ports:
       - "18333:18333"

package/dist/templates/hello-web/html/app.js

@@ -1,23 +1 @@
-import { createSynologyClient } from "./sdk.js";
-
-const status = document.getElementById("status");
-const userEl = document.getElementById("user");
-
-const client = createSynologyClient();
-
-try {
-  await client.auth.requireLogin();
-  const user = await client.auth.getCurrentUser();
-  if (status) {
-    status.textContent = "Signed in with DSM";
-  }
-  if (userEl) {
-    userEl.textContent = user.username;
-  }
-} catch (error) {
-  const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
-  const message = error instanceof Error ? error.message : String(error);
-  if (status) {
-    status.textContent = code === "UNAUTHENTICATED" ? "DSM login required" : message;
-  }
-}
+document.getElementById("status").textContent = "Your app is running.";

package/dist/templates/hello-web/html/index.html

@@ -7,9 +7,7 @@
   </head>
   <body>
     <h1>Hello Web</h1>
-    <p id="status">Opening with your DSM session…</p>
-    <p id="user"></p>
-    <script src="./bootstrap.js"></script>
+    <p id="status">Loading…</p>
     <script type="module" src="./app.js"></script>
   </body>
 </html>

package/dist/templates/hello-web-page/compose.yaml

@@ -1,16 +1,19 @@
 services:
   web:
     image: busybox:1.36
-    # 兩個平台限制，改動前先看 docs/impl/STATUS.md 的 2026-08-24 段：
-    # 1) command／entrypoint 陣列不得有純數字元素（例如 "18333"）。DSM 的
-    #    docker-project worker 會在 YAML round-trip 時掉引號、把它變成整數，
-    #    postinst acquire 直接失敗（error 276 → 套件 broken/150，且 worker_msg
-    #    為空，開發者看不到原因）。所以 port 要包在單一字串裡。
-    #    `synopkgland validate` 已會擋這個寫法。
-    # 2) 預設不用 8080：那個 port 在真實 NAS 上很常被既有容器占用，而 port
-    #    衝突同樣以那個看不出原因的 broken/150 呈現。
-    # 官方 nginx image 也不能用：resource worker 注入任意 package UID/GID，
-    # nginx entrypoint 啟動階段需要 root，會在該身分下直接退出。
+    # DSM worker constraints to preserve when changing this service:
+    # 1) command/entrypoint arrays must not contain bare numeric elements
+    #    (such as "18333"). DSM's docker-project worker drops the quotes on a
+    #    YAML round-trip and turns them into integers, so postinst acquire
+    #    fails (error 276 -> package broken/150, with an empty worker_msg that
+    #    tells the developer nothing). Keep the port inside one string.
+    #    `synopkgland validate` already rejects the bare form.
+    # 2) The default is not 8080: that port is often taken by an existing
+    #    container on a real NAS, and the conflict shows up as the same
+    #    unexplained broken/150.
+    # The official nginx image cannot be used either: the resource worker
+    # injects an arbitrary package UID/GID, and the nginx entrypoint needs
+    # root during startup, so it exits immediately under that identity.
     command: ["sh","-c","httpd -f -p 18333 -h /usr/share/nginx/html"]
     ports:
       - "18333:18333"

package/dist/templates/hello-web-page/html/app.js

@@ -1,23 +1 @@
-import { createSynologyClient } from "./sdk.js";
-
-const status = document.getElementById("status");
-const userEl = document.getElementById("user");
-
-const client = createSynologyClient();
-
-try {
-  await client.auth.requireLogin();
-  const user = await client.auth.getCurrentUser();
-  if (status) {
-    status.textContent = "Signed in with DSM";
-  }
-  if (userEl) {
-    userEl.textContent = user.username;
-  }
-} catch (error) {
-  const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
-  const message = error instanceof Error ? error.message : String(error);
-  if (status) {
-    status.textContent = code === "UNAUTHENTICATED" ? "DSM login required" : message;
-  }
-}
+document.getElementById("status").textContent = "Your app is running.";

package/dist/templates/hello-web-page/html/index.html

@@ -7,9 +7,7 @@
   </head>
   <body>
     <h1>Hello Web Page</h1>
-    <p id="status">Opening with your DSM session…</p>
-    <p id="user"></p>
-    <script src="./bootstrap.js"></script>
+    <p id="status">Loading…</p>
     <script type="module" src="./app.js"></script>
   </body>
 </html>

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

@@ -0,0 +1,268 @@
+# __DISPLAY_NAME__
+
+A native DSM package (`__PACKAGE__`): a Go backend that DSM runs as a CGI,
+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   (backend/, runs as package user)
+      1. transport guards: POST, JSON, same origin, ≤ 1 MiB
+      2. one DSM authentication (unless the route is Public)
+      3. route policy: User or Admin  → refusal before any handler
+      4. your handler (backend/internal/app)
+```
+
+## Quick start
+
+Needs Node.js with `synopkgland` installed, and Go 1.24+.
+
+```bash
+(cd backend && go test ./...)   # auth policy + route tests
+synopkgland build-spk           # → dist/__PACKAGE__-0.1.0-0001-{x86_64,aarch64}.spk
+synopkgland inspect --spk 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 |
+| `ui/…` | Any other assets; served from `/webman/3rdparty/__PACKAGE__/app/` | Yes |
+| `i18n/messages/<locale>.json` | UI text in nine languages | Yes |
+| `i18n/glossary.json` | Synology's official DSM terms, and which messages must use them | Add terms |
+| `backend/internal/app/` | Your API: routes and handlers | Yes — your backend |
+| `backend/internal/api/` | The CGI front door: guards, auth order, route policies | Rarely |
+| `backend/internal/dsm/` | DSM session check and administrators lookup | Rarely |
+| `backend/cmd/app/` | Wires the above together | Rarely |
+| `dist/` | Built SPKs (ignored by git) | No |
+
+`build-spk` generates everything else: `INFO`, `conf/privilege`
+(`run-as: package`), no-op lifecycle scripts, icons, the DSM window wrapper
+(`ui/config`, `ui/window-<build>.js`) and the CGI at `ui/cgi/api.cgi`.
+
+## Add an API operation
+
+Add a route in `backend/internal/app/routes.go`. The policy is part of the
+route, so you cannot register a handler without one:
+
+```go
+func Routes(cfg Config) []api.Route {
+	return []api.Route{
+		api.User("app.status", cfg.status),
+		api.User("greeting.get", cfg.getGreeting),
+		api.Admin("greeting.set", cfg.setGreeting),
+		api.User("notes.list", cfg.listNotes),   // new: any signed-in user
+		api.Admin("notes.purge", cfg.purgeNotes), // new: administrators only
+	}
+}
+
+func (cfg Config) listNotes(ctx context.Context, caller api.Caller, params json.RawMessage) (any, error) {
+	var in struct{ Limit int `json:"limit"` }
+	if err := decodeParams(params, &in); err != nil {
+		return nil, err
+	}
+	return map[string]any{"owner": caller.User(), "notes": []string{}}, nil
+}
+```
+
+Then add the method's valid params to `sampleParams` in `routes_test.go`; the
+test fails until you do, and once you do it proves the new route refuses
+callers without a session (and non-admins, for `api.Admin`) without touching
+the data folder.
+
+Call it from the UI with `ctx.call("notes.list", { limit: 20 })`. Errors
+reject with `{ code, message }`, for example `session_required`,
+`admin_required`, `bad_request` or `internal`.
+
+### Who can call what
+
+| Declared with | No session | Signed-in user | Administrator |
+| --- | --- | --- | --- |
+| `api.User` | `session_required` | runs | runs |
+| `api.Admin` | `session_required` | `admin_required` | runs |
+| `api.Public` | runs | runs | runs |
+| not registered | `session_required` | `unknown_method` | `unknown_method` |
+
+Every reply, error or not, is HTTP 200 with `{"success": false, "error":
+{"code", "message"}}` on failure, the same convention as DSM's own WebAPI.
+DSM's web server replaces the body of any CGI reply with status 403, 404 or
+5xx by its own HTML error page, so a status-coded error would never reach your
+UI.
+
+- Handlers get an `api.Caller` the server built after authenticating; code
+  outside `internal/api` cannot construct an authenticated one.
+- `api.Public` runs with **no** DSM login. Use it only for data you would show
+  anyone who can reach DSM's port; the template ships none.
+- "Administrator" means a member of DSM's `administrators` group, read fresh
+  from `/etc/group` on every request.
+
+## How authentication works (and its limits)
+
+The CGI hands only the session carriers (`Cookie`, `X-SYNO-TOKEN`, client
+address) to DSM's own `/usr/syno/synoman/webman/modules/authenticate.cgi`,
+which prints the signed-in user name. The backend never parses the session
+cookie and never takes a user name or admin flag from the request.
+
+Cross-site requests are refused: the API accepts only `POST` with
+`Content-Type: application/json` (which forces a CORS preflight DSM never
+approves), and it rejects `Sec-Fetch-Site` other than `same-origin` and any
+foreign `Origin`. The DSM window wrapper sends DSM's `SynoToken`, but when DSM
+has `enable_syno_token=no` that token proves nothing, so the same-origin
+checks are what stop cross-site requests.
+
+Known limits:
+
+- Each request reuses the browser's DSM session; it does not carry DSM's
+  per-request `X-SYNO-HASH` proof. Verifying that proof needs private,
+  version-specific DSM libraries through a C bridge, so it is not part of this
+  template.
+- Users from a directory service (LDAP/AD) who are administrators only
+  through directory groups are not listed in `/etc/group`, so they count as
+  ordinary users. This errs towards refusal.
+
+## Customize the UI
+
+`ui/app.js` must register `window.DsmPackageApps[<package>].mount(root, ctx)`
+(the template shows how, using `document.currentScript.dataset.package`).
+`ctx.call(method, params)` is the only transport. `ctx.reopen(fn)` runs `fn`
+whenever DSM shows the window again. Scope your CSS under your own root class:
+every DSM app shares one page.
+
+To build the UI with Vite, Vue or React, point `ui` at the build output and
+give the build command as an argv list (no shell):
+
+```yaml
+ui:
+  dir: web/dist
+  build:
+    cwd: web
+    command: [npm, run, build]
+```
+
+The build must emit `app.js` (one script that registers `mount`) and
+`app.css`. The public `@synopackageland/ui@0.4.0` package on
+`https://registry.npmjs.org` gives Vue components with DSM 7 styling;
+import its `themes/dsm7-embedded.css` for use inside a DSM window.
+
+## Languages
+
+The UI ships in nine of DSM's languages: `en`, `zh-TW`,
+`zh-CN`, `ja`, `ko`, `de`, `fr`, `es` and `it`. DSM's other languages show
+English. The window follows DSM's own language setting (`_S("lang")`).
+
+- **Messages**: `i18n/messages/<locale>.json`, flat `"key": "text"`. Use
+  `ctx.t("greeting.setBy", { text, user })` in the UI; `{name}` is a
+  placeholder, and `ctx.t("files", { count: 3 })` picks `files.one` or
+  `files.other`. Missing keys fall back to English, then to the key itself.
+  `build-spk` embeds the catalogs in the DSM window script, so there is no
+  extra request.
+- **Errors**: the backend returns a `code`; the UI shows
+  `error.<code>` from the catalogs and uses the backend's English text only for
+  codes it has no message for. Add `error.<code>` for every code you return.
+- **Glossary**: `i18n/glossary.json` records DSM's own words in all nine
+  languages, each with its source (`section/key` in DSM 7.4's
+  `/usr/syno/synoman/webman/texts/<lang>/strings`). A term's `keys` lists the
+  messages that must contain it; that is how "Save" uses DSM's own word in
+  every language, the same as the rest of DSM. Product names in `untranslated`
+  stay in English everywhere.
+- **Package Center text**: `i18n.info` in `dsm-package.yaml` writes INFO
+  `displayname_<lang>` / `description_<lang>` (for example `description_cht`).
+
+`synopkgland validate` and `build-spk` refuse a language file with missing or
+extra keys, a translation that drops a `{placeholder}`, an unsupported
+language, or a listed message that drifts from the glossary.
+
+To add a message: add the key to `en.json` and to the other eight files. To
+use a DSM term, copy its `text` from the glossary and add your key to the
+term's `keys`. A Vue or React UI can keep its own i18n library; `ctx.t` and
+`ctx.locale` are there if you want them.
+
+## Package an existing binary
+
+Keep the Go backend and call your tool from a handler (recommended: auth
+stays central), or replace the CGI with your own executable:
+
+```yaml
+arches: [x86_64]
+backend:
+  binary:
+    x86_64: prebuilt/api-x86_64
+```
+
+The file must be a regular file in the project, a 64-bit Linux ELF for that
+arch, and statically linked (DSM models ship different libc versions). It is
+installed as `ui/cgi/api.cgi` (mode 0755) and runs as the package account.
+It then owns everything `backend/internal/api` does for you: bounded reads,
+POST-only JSON, same-origin checks, authentication before any work, and a
+refusal for unknown methods.
+
+## Data, upgrades, uninstall
+
+The backend stores data in `/var/packages/__PACKAGE__/var` (the package's
+own folder, kept across upgrades). Bump `build` for every SPK you hand out;
+bump `version` for feature releases. There are no lifecycle scripts to write:
+the CGI starts per request, so start/stop do nothing.
+
+## Root access
+
+By default (`privilege: none`) nothing in this package ever runs as root, and
+that is the right choice for almost every app. Lifecycle scripts and the CGI
+run as the package account, and nothing the package account can write is ever
+run as root.
+
+If your app truly needs root for a few fixed actions, create the project with
+`synopkgland init -t native-go --privilege root`. That sets `privilege: root`
+and adds:
+
+- `root/whoami.sh`: one root operation. Each `root/<name>.sh` (lowercase name,
+  `#!/bin/sh`, at most 16 KiB) is one operation. The demo only reports the
+  user ID it runs as (`{"euid":0}`). Replace it with your own fixed actions.
+- `backend/internal/app/root.go`: the `root.output` route (administrators
+  only) that returns an operation's last result.
+
+How it works, with no keys or signing involved:
+
+1. `build-spk` embeds each operation's exact task text in the DSM window. The
+   SPK payload carries no root script, and the package still runs as its own
+   account.
+2. The window shows an authorization panel above your app, in the user's
+   DSM language. A DSM administrator clicks **Authorize** and confirms with
+   their DSM password in DSM's own dialog. DSM then creates one **disabled**
+   root task in Task Scheduler, named `<package> root: <name>`. The
+   confirmation is used for that one task and never stored.
+3. **Run** checks that the task is still exactly the approved text, runs it
+   with the administrator's session and shows its result. The task writes
+   only to `/run/synopkgland-<package>/<name>.out`, which root owns and your
+   backend can only read.
+4. The task text includes the package version, so after an upgrade the panel
+   shows "needs authorization again" and the old task never runs. A
+   same-named task that the panel did not create is never run, replaced or
+   deleted.
+5. **Remove** deletes the task, also an outdated one, without asking for the
+   password. Remove it before uninstalling the package, because DSM keeps
+   Task Scheduler tasks after an uninstall.
+
+Non-administrators see DSM's "Only administrator accounts can perform this
+operation." and nothing else. HTTP requests can never choose what runs as
+root: the only root code is the fixed text an administrator approved. Your app
+can also use `ctx.root` (`state`, `authorize`, `run`, `remove`, `output`) to
+drive the same flow from its own UI.
+
+## Support matrix
+
+| | Status |
+| --- | --- |
+| Build hosts | macOS, Linux (any OS with Go and Node) |
+| Target CPUs | x86_64 and aarch64 DSM models (one SPK each) |
+| DSM | 7.2 or later declared (`os_min_ver`). Installed and tested on DSM 7.4 (x86_64). aarch64 SPKs are built the same way but have not been run on a NAS. |
+| Not supported | 32-bit ARM, DSM 6, running anything as root without an administrator's approval |