@synopackageland/cli 0.35.0 → 0.37.0

package/dist/standalone/spk.js

@@ -1,4 +1,5 @@
 import { settingsInstallSteps, settingsConfig } from './install-settings.js';
+import { backupConfig, backupHookProblem, backupRecord, renderBackupScripts, BACKUP_PAYLOAD_DIR, BACKUP_SCRIPTS_DIR, BACKUP_SCRIPT_MODES } from './hyper-backup.js';
 import { nativeGatewaySupported, nativeGatewaySdk, renderNativeGatewayConfig, NATIVE_GATEWAY_CONFIG, legacyGatewayNotice, gatewayEntryPath } from './native-gateway.js';
 import { portalInfoFields } from "../portal/info.js";
 import { sdkSource } from "../runtime/sdk-source.js";
@@ -13,7 +14,7 @@ import { infoArchValue } from "../build-spk/dsm-arch.js";
 import { packageIcons, writeDsmWindowIcons, writePackageCenterIcons, } from "../build-spk/dsm-icons.js";
 import { renderNativePrivilege } from "../build-spk/native-lifecycle.js";
 import { renderUninstallWizardFiles } from "../build-spk/uninstall-wizard.js";
-import { renderInstallWizardFiles, renderNativeInstallWizard, } from "../build-spk/install-wizard.js";
+import { renderInstallWizardFiles, integrationWizardSteps, renderNativeInstallWizard, } from "../build-spk/install-wizard.js";
 import { writeWizardUiFiles, } from "../build-spk/wizard-i18n.js";
 import { renderDelegateScopeSteps } from "../build-spk/delegate-scope.js";
 import { createReproducibleTar } from "../build-spk/reproducible-archive.js";
@@ -40,7 +41,7 @@ import { portalByExecutor } from "../build-spk/dsm-version.js";
 import { PORTAL_JSON_RELPATH, PORTAL_MUSTACHE_RELPATH, renderPortalJson, renderPortalMustache, renderPortalWizardStep, } from "../portal/package.js";
 import { executorPlan, } from "../runtime/executor-build.js";
 import { EXECUTOR_ANCHOR } from "../runtime/executor-inspect.js";
-import { renderSharedFolderUpgradeWizardFiles, sharedFolderInstallSteps, } from "./shared-folder.js";
+import { renderUpgradeWizardFiles, sharedFolderInstallSteps, } from "./shared-folder.js";
 import { stateItemTexts, uninstallExecProblem, uninstallRecord, } from "./uninstall.js";
 const FILE_MODE = 0o644;
 const EXEC_MODE = 0o755;
@@ -225,6 +226,14 @@ export async function assembleStandaloneSpk(options) {
             copyExecutable(options.installSettingsControl, join(target, 'control'));
             writeFile(join(target, 'settings.json'), JSON.stringify(settingsConfig(manifest), null, 2) + '\n');
         }
+        const backup = options.appBackupControl ? manifest.hyperBackup : undefined;
+        if (backup) {
+            const hook = backupHookProblem(join(staging, "package"), backup);
+            if (hook)
+                throw new StandaloneBuildError("BACKUP_HOOK_MISSING", hook);
+            copyExecutable(options.appBackupControl, join(staging, "package", BACKUP_PAYLOAD_DIR, "control"));
+            writeFile(join(staging, "package", BACKUP_PAYLOAD_DIR, "config.json"), backupConfig(manifest.package, backup));
+        }
         const packageTgz = join(staging, "package.tgz");
         await createReproducibleTar(join(staging, "package"), packageTgz, {
             gzip: true,
@@ -237,6 +246,8 @@ export async function assembleStandaloneSpk(options) {
             schema: 2,
             ...(moduleVersion ? { ui_module: moduleVersion } : {}),
             ...(manifest.installSettings ? { installSettings: manifest.installSettings } : {}),
+            ...(backup ? { hyperBackup: backupRecord(backup) } : {}),
+            ...(manifest.integrations ? { integrations: manifest.integrations } : {}),
             ...(manifest.lifecycleTimeouts ? { lifecycleTimeouts: manifest.lifecycleTimeouts } : {}),
             ...("timeoutSeconds" in manifest.backend && manifest.backend.timeoutSeconds ? { operationSeconds: manifest.backend.timeoutSeconds } : {}),
             ...(options.apiDescription ? { ctl: { hash: options.apiDescription.sha256, registry: options.apiRegistry } } : {}),
@@ -282,6 +293,11 @@ export async function assembleStandaloneSpk(options) {
         for (const name of LIFECYCLE_SCRIPTS) {
             writeFile(join(staging, "scripts", name), renderStandaloneScript(name, manifest), EXEC_MODE);
         }
+        if (backup) {
+            mkdirSync(join(staging, BACKUP_SCRIPTS_DIR));
+            for (const [name, text] of Object.entries(renderBackupScripts(backup)))
+                writeFile(join(staging, BACKUP_SCRIPTS_DIR, name), text, BACKUP_SCRIPT_MODES[name]);
+        }
         for (const name of manifest.appScripts ?? [])
             copyExecutable(join(manifest.root, APP_SCRIPTS_DIR, name), join(staging, APP_SCRIPTS_SPK_DIR, name));
         const folder = manifest.sharedFolder;
@@ -295,13 +311,11 @@ export async function assembleStandaloneSpk(options) {
             : folder
                 ? sharedFolderInstallSteps(manifest.package, folder)
                 : renderNativeInstallWizard;
-        const install = renderInstallWizardFiles(manifest.package, (t) => [...steps(t), ...settingsInstallSteps(manifest.installSettings)(t), ...(portal ? [renderPortalWizardStep(t, portal.alias)] : [])]);
+        const install = renderInstallWizardFiles(manifest.package, (t) => [...steps(t), ...settingsInstallSteps(manifest.installSettings)(t), ...(portal ? [renderPortalWizardStep(t, portal.alias)] : []), ...integrationWizardSteps(t, manifest.integrations)]);
         writeWizardUiFiles(staging, {
             ...install.static,
             ...install.dynamic,
-            ...(folder
-                ? renderSharedFolderUpgradeWizardFiles(manifest.package, folder)
-                : {}),
+            ...renderUpgradeWizardFiles(manifest.package, folder, manifest.integrations),
             ...renderUninstallWizardFiles(manifest.package, "native", {
                 composeData: manifest.compose?.plan.app_data,
                 executor: Boolean(options.executor),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "~0.32.0",
+    "@synopackageland/templates": "~0.33.0",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-CLI 0.35.0 installs templates through `~0.32.0`. A templates patch needs only a
+CLI 0.36.0 installs templates through `~0.32.0`. A templates patch needs only a
 templates release; npm install/update selects a patch in that minor line. The CLI
 uses the locally installed templates and reads their SDK pin for defaults; it
 never downloads templates at runtime. Preserve the lockfile and use `npm ci` for
@@ -24,7 +24,7 @@ Use this guide to initialize, build and inspect own applications or upstream OSS
 
 For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.3 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
 
-Use SDK 0.33.0 and CLI 0.35.0 for App entry enforcement. Declare every App method
+Use SDK/App 0.35.0 and CLI 0.37.0 for App entry enforcement. Declare every App method
 in the permissions table; dynamic names and unregistered HTTP dispatchers are rejected.
 Use fixed SDK routes and `identity_gateway.upstream_auth_paths` for client API
 paths that rely on upstream authentication. Read
@@ -41,6 +41,36 @@ cannot upgrade a connection; use an existing upgrade-capable deployment
 transport. The audit follows each configured Go binary's Linux import graph,
 including declared workers; unshipped dev commands are excluded.
 
+Use `ipc.StartUnix(ctx, path, handler)` for multiple private data-plane sockets.
+Each direct `.sock` child of the package `var/run` gets an independent handle
+with Close, Shutdown and Wait. Stop/revoke closes active streams and hijacked
+connections, including WebSocket; keep target approval and pin checks in the
+handler. A private socket may serve the upstream root path without CGI.
+For official supervised children use `ipc.ReserveLoopback(ctx, 0)` to hold a
+127.0.0.1 TCP port, read Port/Address and Release immediately before starting
+the child. `ipc.ProbeLoopback(ctx, port)` checks a specific port without
+retaining it. Check child readiness and retry bind conflicts: release-to-bind
+is inherently racy. Never replace these with custom listeners or fixed ports.
+
+An optional root helper is a separately approved executor payload.
+`ipc.ServePeerUnix(ctx, path, ipc.PeerPolicy{UID: uid, GID: gid}, handler)`
+supports a bounded raw JSON control protocol on a root-owned 0660 socket under
+`/var/run/synopkgland/<package>/`. The SDK authenticates exactly the selected
+UID with SO_PEERCRED; the handler validates bounded frames and current
+authorization. `ipc.DialPeerUnix` verifies root ownership, protected ancestors,
+mode and server UID zero. The server requires root AND the helper's explicit
+`ipc.executorTier=executor` linker binding. Bind packageID in custom builds.
+Generated CGI/workers bind tier `none`; never launch or install them as root.
+The transport does not provide installation, approval or privilege elevation.
+
+Audit every custom-hook Go payload with
+`synopkgland audit-entry ./cmd/helper --dir backend --arch amd64,arm64,arm --json`
+before packaging. Use `--permissions` when it registers App methods.
+Each entry is checked against its actual target import graph, including every
+file of shared packages. Unused server functions have no exemption. Use real
+client/server packages or supported SDK boundaries; no App allowlists, hidden
+directories, aliases or ABI workarounds.
+
 **If you package someone else's open-source project, set `maintainer` to the
 original project/owner (prefer the project's own team/org name, else the owner's
 display name, else login), `metadata.maintainer_url` to the upstream repository,
@@ -61,6 +91,8 @@ Read reference/portal.md before declaring or changing a DSM Application Portal a
 
 Read [reference/lifecycle.md](reference/lifecycle.md) before editing `dsm-scripts/` (preinst, postinst, preupgrade, postupgrade, preuninst, postuninst, start-stop-status): the SDK runs them inside its generated scripts as the package account; never add root work or repeat SDK steps there.
 
+Native Apps appear in Hyper Backup as applications by default. Read [reference/backup.md](reference/backup.md) before changing `backup` in dsm-package.yaml (opt out with `hyper_backup: false`, online mode, data version, hook). Hyper Backup runs the generated `scripts/backup/` as root; it is a fixed template that only switches to the package account, so never add or edit files there.
+
 Read [reference/ui-vue.md](reference/ui-vue.md) when editing Vue components in the native-go Vue template; use the installed SDK contracts, keep DSM embedding boundaries, and verify the actual app.
 
 Buttons follow DSM's policy ([reference/ui-vue.md](reference/ui-vue.md#buttons), the UI package's `docs/button-policy.md`): only the bar that closes a dialog, wizard or form draws capsules, with Cancel/Reset first and one primary (or one danger to confirm a deletion) last; toolbar, page, section and row actions are grey tool buttons, Delete included; links go to `Link`. Choose the variant, never the shape.

package/skills/reference/backup.md

@@ -0,0 +1,70 @@
+# Hyper Backup application backup
+
+Native Apps (Go, Python, Node, Rust and binary backends) appear as applications
+in Hyper Backup's backup wizard by default. An administrator selects the App in
+a backup task and restores it from that task later. Compose Apps keep their
+data in container volumes, which this does not cover, so it is off for them
+and `backup` is refused for a Compose App.
+
+## Declaration
+
+Nothing to declare for the default: offline backup of the whole data folder,
+data version `1.0`.
+
+```yaml
+backup:
+  online: false          # default; true keeps the App running during a backup
+  data_version: "1.0"    # "major.minor", see below
+  hook: bin/backup-hook  # optional, relative to the package target
+```
+
+Opt out with exactly:
+
+```yaml
+backup:
+  hyper_backup: false
+```
+
+- **Offline** (default): Hyper Backup stops the App, the SDK archives the data
+  folder, and Hyper Backup starts the App again.
+- **Online**: the App keeps running; SQLite databases are copied through
+  SQLite's backup API, their journals are left out, other files are copied as
+  they are. Use it only when other files stay consistent while the App runs,
+  or add a hook.
+- **Hook**: a packaged executable run as the package account as `<hook> freeze`
+  before the export and `<hook> thaw` after it. It writes only to standard
+  error. The build fails with `BACKUP_HOOK_MISSING` when the file is not an
+  executable in the package.
+- **Data version**: a restore accepts the same package with the same major
+  version and an equal or lower minor version; otherwise it refuses and keeps
+  the current data. Raise the minor version when the App migrates older data
+  itself, the major version when it cannot.
+
+Restore always runs with the App stopped and replaces the whole data folder
+(the package's `var`). It needs the App installed first.
+
+## What runs as root
+
+Hyper Backup runs a package's backup scripts as root. This is a DSM-owned hook,
+not App runtime: the App still runs as its package account, and the SDK
+privilege tiers for App code are unchanged. The CLI writes the root part from a
+fixed template. It switches to the owner of the App's data folder (refusing
+root), runs the SDK backup control as that account, and moves one archive
+between that account and Hyper Backup's temporary folder without reading it.
+The package ships no script that Hyper Backup would run while only listing
+applications.
+
+Never add files to `scripts/backup/` or edit them. `check` validates the
+`backup` declaration and reports it as `hyperBackup` in `--json`; `inspect`
+verifies the exact bytes of the scripts, the SDK control and its config, and
+refuses any other file there, such as `can_export` or `info.dynamic`.
+
+## Errors
+
+| Code | Meaning |
+| --- | --- |
+| `BACKUP_INVALID` | Bad `backup` declaration, or packaged backup files differ from what build writes |
+| `BACKUP_COMPOSE_UNSUPPORTED` | `backup` on a Compose App |
+| `BACKUP_HOOK_MISSING` | `backup.hook` is not an executable in the package |
+| `SDK_APP_BACKUP_UNSUPPORTED` | The SDK has no backup control; a default build skips backup with this warning, an explicit `backup` fails |
+| `SDK_APP_BACKUP_BUILD_FAILED` | The SDK backup control did not build; when Go is not installed (a prebuilt backend), a default build skips backup with this warning, an explicit `backup` fails |