@synopackageland/cli 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.37.0 (2026-10-29)
+
+- Native Apps appear in Hyper Backup as applications by default. Build writes
+  `scripts/backup/{version,info,export,import}` from a fixed template and ships
+  the SDK backup control as `backup/control` with `backup/config.json`.
+  Hyper Backup runs the scripts as root; they only switch to the owner of the
+  App's data folder (refusing root), run the control as that package account
+  and move one archive they never read. Offline backup is the default
+  (Hyper Backup stops and restarts the App); `backup.online`,
+  `backup.data_version` and `backup.hook` are optional, and
+  `backup: {hyper_backup: false}` opts out. Compose Apps are not covered.
+  `check --json` reports `hyperBackup`; `inspect` verifies the exact script
+  bytes, modes, control and config, and refuses any other file in
+  `scripts/backup/`, such as `can_export` or `info.dynamic`, which Hyper
+  Backup would run as root while only listing applications. An SDK without
+  the control skips the default with `SDK_APP_BACKUP_UNSUPPORTED`; without Go
+  (prebuilt backends) it is skipped with `SDK_APP_BACKUP_BUILD_FAILED`; an
+  explicit `backup` fails in both cases. New
+  errors: `BACKUP_INVALID`, `BACKUP_COMPOSE_UNSUPPORTED`,
+  `BACKUP_HOOK_MISSING`, `SDK_APP_BACKUP_UNSUPPORTED`,
+  `SDK_APP_BACKUP_BUILD_FAILED`. New skill reference `backup`.
+- Rebuilt native Apps gain a fixed `scripts/backup/` shim that Hyper Backup
+  runs as root. The App itself still runs as the package user, and its
+  privilege tier is unchanged. Opt out with `backup: { hyper_backup: false }`.
+- Pin SDK/App 0.35.0.
+
 ## 0.36.0 (2026-10-29)
 
 - Stop treating `net.Listener` and `net.ListenConfig` types as listeners.

package/README.md

@@ -74,7 +74,7 @@ alongside npm lockfiles. Do not disable checksum verification for public SDK
 packages. Private mirrors can use explicitly configured Go authentication and
 checksum settings; a failed fetch reports `SDK_DOWNLOAD_FAILED`.
 
-CLI 0.35.0 uses templates ~0.32.0, whose default SDK pin remains 0.32.0. Compose import and SDK defaults
+CLI 0.37.0 uses templates ~0.33.0, whose default SDK pin is 0.35.0. Compose import and SDK defaults
 read the SDK pin from the installed templates; explicit App SDK declarations take precedence.
 Every App method must be declared in the permissions table. Dynamic names and
 custom HTTP dispatchers are rejected. With SDK 0.33.0, use fixed
@@ -85,8 +85,8 @@ unimported development commands are excluded. Use
 authentication. See [App entry and registration](docs/app-entry.md).
 
 `init` and `add` read their templates from the locally installed
-`@synopackageland/templates`. CLI 0.35.0 depends on `~0.32.0`: npm installation or
-update can select the latest templates patch in the 0.32 minor line. Templates
+`@synopackageland/templates`. CLI 0.37.0 depends on `~0.33.0`: npm installation or
+update can select the latest templates patch in the 0.33 minor line. Templates
 patches need only a templates release; update the npm installation to receive them.
 The CLI never fetches templates at runtime, so offline use works after installation;
 commit a lockfile and use `npm ci` to reproduce a chosen dependency tree.
@@ -173,6 +173,18 @@ template changes and executor-only handover eligibility. Without a comparable
 baseline, approval retention is unknown. Eligibility still requires live protected
 runtime and exact DSM task readback. See [the approval guide](skills/reference/approval-upgrades.md).
 
+## Hyper Backup
+
+Native Apps appear in Hyper Backup's backup wizard as applications. By default Hyper Backup stops
+the App, the SDK archives its data folder (the package's `var`) and Hyper Backup starts it again;
+a restore replaces that folder. `backup: {online: true}` keeps the App running and snapshots
+SQLite databases; `data_version` guards restores of newer data; `hook` runs a packaged
+`freeze`/`thaw` executable; `backup: {hyper_backup: false}` opts out. Compose Apps are not
+covered. The build compiles the SDK backup control with Go, also for a prebuilt backend; without
+Go it skips the default backup with a warning. Hyper Backup runs the generated `scripts/backup/` as root: a fixed script that only
+switches to the package account and moves one archive it never reads. This DSM-owned hook does
+not change how the App runs or its privilege tier. See `synopkgland skill show backup`.
+
 ## Commands
 
 | Command | Purpose |

package/dist/cli.js

@@ -38,6 +38,7 @@ import { checkJobs, commitOutputs, forEachArch, } from "./standalone/arch-jobs.j
 import { checkReproducible } from "./reproducible.js";
 import { spkApprovalDiff, formatApprovalDiff } from "./runtime/approval-diff.js";
 import { inspectAnySpk } from "./spk/inspect.js";
+import { backupRecord } from "./standalone/hyper-backup.js";
 import { terminalSafe } from "./terminal-text.js";
 import { auditGoRoutes } from "./standalone/route-audit.js";
 import { parseApiPermissions } from "./standalone/api-permissions.js";
@@ -125,10 +126,14 @@ function formatRootSteps(report) {
 function formatInstallSettings(settings) {
     return settings ? Object.entries(settings).map(([key, s]) => `Installation setting ${key}: ${s.type}, ${s.required ? 'required' : 'optional'} (${s.label}); values are private`) : [];
 }
+function formatHyperBackup(b) {
+    return [b ? `Hyper Backup: application backup on, ${b.online ? 'online (App keeps running; SQLite snapshots)' : 'offline (App stopped during export)'}, data version ${b.dataVersion}${b.hook ? `, hook ${b.hook}` : ''}. Hyper Backup runs the fixed backup scripts as root; they only switch to the package account.` : 'Hyper Backup: application backup off'];
+}
 function formatSpkReport(spk, report) {
     return [
         `SPK: ${spk}`,
         ...formatInstallSettings(report.installSettings),
+        ...(report.synopkgland ? formatHyperBackup(report.hyperBackup) : []),
         ...(report.identityGateway ? [report.identityGateway.notice, `OIDC issuer access: ${report.identityGateway.issuerAccess}`] : []),
         `package: ${report.package ?? "?"}  version: ${report.version ?? "?"}`,
         report.synopkgland
@@ -401,6 +406,7 @@ async function runCliWithin(argv) {
                 package: loaded.manifest.package,
                 warnings: validation.warnings ?? [],
                 ...("installSettings" in loaded.manifest && loaded.manifest.installSettings ? { installSettings: loaded.manifest.installSettings } : {}),
+                ...("hyperBackup" in loaded.manifest && loaded.manifest.hyperBackup ? { hyperBackup: backupRecord(loaded.manifest.hyperBackup) } : {}),
                 ...("identityGateway" in loaded.manifest && gatewayAdmissionReport(loaded.manifest.identityGateway, loaded.manifest.entry) ? { identityGateway: gatewayAdmissionReport(loaded.manifest.identityGateway, loaded.manifest.entry) } : {}),
                 capabilities: "capabilities" in loaded.manifest
                     ? loaded.manifest.capabilities
@@ -423,6 +429,7 @@ async function runCliWithin(argv) {
             }, [
                 "Validation passed.",
                 ...formatInstallSettings("installSettings" in loaded.manifest ? loaded.manifest.installSettings : undefined),
+                ...("capabilities" in loaded.manifest ? formatHyperBackup(loaded.manifest.hyperBackup) : []),
                 ...("identityGateway" in loaded.manifest && gatewayAdmissionReport(loaded.manifest.identityGateway) ? [gatewayAdmissionReport(loaded.manifest.identityGateway).notice] : []),
                 ...("compose" in loaded.manifest && loaded.manifest.compose
                     ? [

package/dist/error-registry.js

@@ -15,6 +15,11 @@ export const ERROR_REGISTRY = {
     INSTALL_SETTINGS_INVALID: { "code": "INSTALL_SETTINGS_INVALID", "description": "The installation setting declaration is invalid.", "suggestion": "Declare 1–32 lowercase identifier keys in install.settings, each with type https-origin, a plain label and an explicit boolean required; omit defaults and values." },
     SDK_INSTALL_SETTINGS_UNSUPPORTED: { "code": "SDK_INSTALL_SETTINGS_UNSUPPORTED", "description": "The selected SDK does not provide native installation settings.", "suggestion": "Pin SDK 0.24.0 or a matching supported release with installsettings/cmd/control, then rebuild with the matching CLI." },
     SDK_INSTALL_SETTINGS_BUILD_FAILED: { "code": "SDK_INSTALL_SETTINGS_BUILD_FAILED", "description": "The SDK installation settings controller could not be built.", "suggestion": "Install the pinned Go toolchain, inspect the compiler diagnostics and rebuild with a complete matching SDK release." },
+    BACKUP_INVALID: { code: "BACKUP_INVALID", description: "The Hyper Backup application backup declaration or its packaged scripts are invalid.", suggestion: "Use backup.hyper_backup: false to opt out, or only online, data_version (\"major.minor\") and hook; rebuild so scripts/backup holds exactly the fixed export, import, info and version files." },
+    BACKUP_COMPOSE_UNSUPPORTED: { code: "BACKUP_COMPOSE_UNSUPPORTED", description: "Compose Apps keep their data in container volumes, which application backup does not cover.", suggestion: "Remove backup from a Compose App or set backup.hyper_backup: false." },
+    BACKUP_HOOK_MISSING: { code: "BACKUP_HOOK_MISSING", description: "backup.hook does not name an executable file in the package.", suggestion: "Package the hook (for example in the daemon payload or the App folder) and give its path relative to the package target." },
+    SDK_APP_BACKUP_UNSUPPORTED: { code: "SDK_APP_BACKUP_UNSUPPORTED", description: "The selected SDK does not provide Hyper Backup application backup.", suggestion: "Pin an SDK release with appbackup/cmd/control, or remove the backup declaration; without one the build skips application backup." },
+    SDK_APP_BACKUP_BUILD_FAILED: { code: "SDK_APP_BACKUP_BUILD_FAILED", description: "The SDK backup control could not be built.", suggestion: "Install the pinned Go toolchain, inspect the compiler diagnostics and rebuild with a complete matching SDK release." },
     INIT_HEALTH_INVALID: { code: "INIT_HEALTH_INVALID", description: "The Compose readiness selection is invalid.", suggestion: "Supply both --health-path and --health-status with the actual endpoint and expected 2xx response; redirects are not followed." },
     INIT_UPSTREAM_IMAGE_REQUIRED: { code: "INIT_UPSTREAM_IMAGE_REQUIRED", description: "The official upstream image repository was not selected.", suggestion: "Use init --upstream-fork --upstream-image <official-repository> for Compose." },
     INIT_UPSTREAM_IMAGE_INVALID: { code: "INIT_UPSTREAM_IMAGE_INVALID", description: "The upstream image repository is invalid.", suggestion: "Supply the official repository without a tag or digest; upgrade.sh selects the matching release and resolves its digest." },

package/dist/skill.js

@@ -52,6 +52,11 @@ const SKILL_CATALOG = [
         file: "reference/lifecycle.md",
         when: "Add work to install, upgrade, uninstall, start or stop (dsm-scripts/)",
     },
+    {
+        id: "backup",
+        file: "reference/backup.md",
+        when: "Change or opt out of Hyper Backup application backup",
+    },
     { id: "deploy", file: "reference/deploy.md", when: "Deploy to a NAS" },
     {
         id: "diagnose",

package/dist/standalone/build.js

@@ -1,4 +1,5 @@
 import { buildInstallSettings } from './install-settings.js';
+import { buildAppBackup } from './hyper-backup.js';
 import { auditGoRoutes, httpRoutesDigest } from './route-audit.js';
 import { PORTAL_REQUIRES_EXECUTOR } from "../portal/alias.js";
 import { buildApiDescription } from "./api-description.js";
@@ -156,6 +157,7 @@ export async function buildStandalone(options) {
             const identityGateway = await buildIdentityGateway(manifest, arch, archWork, run);
             const composeControl = await buildComposeControl(manifest, arch, archWork, run);
             const installSettingsControl = await buildInstallSettings(manifest, arch, archWork, run);
+            const appBackupControl = await buildAppBackup(manifest, arch, archWork, run, (w) => warnings.add(w));
             const composeStorageInit = await buildComposeStorageInit(manifest, arch, archWork, run);
             // A portal needs the executor, so the executor's SDK carries the panel text.
             const portalText = manifest.portal && executor
@@ -171,6 +173,7 @@ export async function buildStandalone(options) {
                 composeControl,
                 composeStorageInit,
                 installSettingsControl,
+                appBackupControl,
                 backgroundWorker,
                 executor,
                 app,

package/dist/standalone/hyper-backup.d.ts

@@ -0,0 +1,59 @@
+import type { StandaloneError, StandaloneManifest } from './manifest.js';
+import type { NativeArchFamily } from '../build-spk/dsm-arch.js';
+import type { CommandRunner } from './build.js';
+/**
+ * `backup`: Hyper Backup application backup. On by default for native Apps.
+ * Hyper Backup runs a package's backup scripts as root, so the scripts are a
+ * fixed template that only switches to the package account and moves one
+ * archive; the SDK control does the rest as the package account.
+ */
+export interface HyperBackup {
+    /** Export while the App runs; SQLite databases are then snapshotted. */
+    online: boolean;
+    /** "major.minor"; a backup restores into the same major and an equal or newer minor. */
+    dataVersion: string;
+    /** A package-relative executable run as `<hook> freeze` and `<hook> thaw` around an export. */
+    hook?: string;
+    /** The App declared `backup`; an SDK without the control is then an error, not a skip. */
+    explicit?: true;
+}
+export declare const DEFAULT_HYPER_BACKUP: HyperBackup;
+/** Hyper Backup's plugin folder inside the SPK. */
+export declare const BACKUP_SCRIPTS_DIR = "scripts/backup";
+/** The SDK control and its config inside the package payload. */
+export declare const BACKUP_PAYLOAD_DIR = "backup";
+export declare function readHyperBackup(value: unknown, context: {
+    compose?: boolean;
+}, fail: (e: StandaloneError) => void): HyperBackup | undefined;
+/** scripts/backup: framework 1.0, the offline/online choice and the two fixed scripts. */
+export declare function renderBackupScripts(b: Pick<HyperBackup, 'online' | 'dataVersion' | 'hook'>): {
+    version: string;
+    info: string;
+    export: string;
+    import: string;
+};
+export declare const BACKUP_SCRIPT_MODES: Record<string, number>;
+export declare function backupConfig(pkg: string, b: HyperBackup): string;
+/** What sdk-package.json records, without the build-only `explicit`. */
+export declare function backupRecord(b: HyperBackup): HyperBackup;
+export declare function readBackupRecord(value: unknown): HyperBackup | undefined;
+/**
+ * Builds the SDK backup control. An SDK release without it skips the default
+ * with a warning; an explicit `backup` declaration then fails.
+ */
+/** The Go package of the SDK backup control; tests use it to tell its build apart. */
+export declare const APP_BACKUP_CONTROL_PACKAGE = "./appbackup/cmd/control";
+export declare function buildAppBackup(m: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner, warn: (w: string) => void): Promise<string | undefined>;
+/** The hook must be a packaged executable. */
+export declare function backupHookProblem(payload: string, b: HyperBackup): string | undefined;
+/**
+ * Inspect: the record, scripts/backup and payload backup/ must be exactly
+ * what build writes, or all absent. Any other file in scripts/backup — such
+ * as can_export or info.dynamic, which Hyper Backup runs as root while it only
+ * lists applications — is refused. The extracted scripts/backup is removed
+ * afterwards so later script checks see the lifecycle scripts alone.
+ */
+export declare function inspectHyperBackup(dir: string, payloadDir: () => Promise<string>, payload: Array<{
+    path: string;
+    mode: string;
+}>, raw: unknown, pkg: string, arch: NativeArchFamily, findings: string[]): Promise<HyperBackup | undefined>;

package/dist/standalone/hyper-backup.js

@@ -0,0 +1,180 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { sdkSource } from '../runtime/sdk-source.js';
+import { goChildEnv } from '../runtime/go-env.js';
+import { pinnedGoBuildEnv, pinnedGoProblem } from '../build-spk/go-toolchain.js';
+import { checkCgiBinary } from './binary.js';
+import { StandaloneBuildError } from './spk.js';
+import { daemonSdkVersion, relativeExec } from './daemon.js';
+export const DEFAULT_HYPER_BACKUP = Object.freeze({ online: false, dataVersion: '1.0' });
+/** Hyper Backup's plugin folder inside the SPK. */
+export const BACKUP_SCRIPTS_DIR = 'scripts/backup';
+/** The SDK control and its config inside the package payload. */
+export const BACKUP_PAYLOAD_DIR = 'backup';
+const FIELDS = new Set(['hyper_backup', 'online', 'data_version', 'hook']);
+const DATA_VERSION = /^(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})$/;
+const INVALID = 'backup accepts hyper_backup: false (opt out) or online (boolean), data_version ("major.minor", default "1.0") and hook (a fixed executable inside the package).';
+const record = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+export function readHyperBackup(value, context, fail) {
+    const bad = () => { fail({ code: 'BACKUP_INVALID', message: INVALID }); return undefined; };
+    if (value === undefined)
+        return context.compose ? undefined : DEFAULT_HYPER_BACKUP;
+    if (!record(value) || Object.keys(value).some(k => !FIELDS.has(k)))
+        return bad();
+    if (value.hyper_backup !== undefined && typeof value.hyper_backup !== 'boolean')
+        return bad();
+    if (value.hyper_backup === false)
+        return Object.keys(value).length === 1 ? undefined : bad();
+    if ((value.online !== undefined && typeof value.online !== 'boolean') ||
+        (value.data_version !== undefined && (typeof value.data_version !== 'string' || !DATA_VERSION.test(value.data_version))) ||
+        (value.hook !== undefined && !relativeExec(value.hook)))
+        return bad();
+    if (context.compose) {
+        fail({ code: 'BACKUP_COMPOSE_UNSUPPORTED', message: 'Hyper Backup application backup covers the package data folder; Compose App data lives in container volumes, so remove backup or set hyper_backup: false.' });
+        return undefined;
+    }
+    return { online: value.online === true, dataVersion: value.data_version ?? '1.0', ...(value.hook ? { hook: value.hook } : {}), explicit: true };
+}
+/**
+ * The root-run part. It reads Hyper Backup's temporary folder, refuses a
+ * root-owned data folder, switches to the data folder's owner (the package
+ * account) and lets that account write or read one archive. It never runs
+ * package content as root and never looks inside the archive. When Hyper
+ * Backup already runs it as another account, it skips the switch.
+ */
+function shim(action) {
+    const io = action === 'export' ? '> "$T/payload.tar"' : '< "$T/payload.tar"';
+    return `#!/bin/sh
+# Generated by synopkgland. Hyper Backup runs this as root. It only switches
+# to the package account and moves one archive; it never reads the archive.
+T=$(printf '%s' "$SYNOPKG_BKP_INPUT" | /usr/bin/jq -er .temp_path) || exit 1
+U=$(/usr/bin/stat -c %u:%g "$SYNOPKG_PKGVAR") || exit 1
+case $U in 0:*|*:0) exit 1 ;; esac
+if [ "$(/usr/bin/id -u)" = 0 ]; then RUN="/usr/bin/chroot --userspec=$U /"; else RUN=; fi
+$RUN /bin/sh -c 'exec "$SYNOPKG_PKGDEST/backup/control" ${action}' ${io} || exit 1
+printf '{"app_data_version":"1.0"}' > "$SYNOPKG_BKP_OUTPUT_PATH"
+`;
+}
+/** scripts/backup: framework 1.0, the offline/online choice and the two fixed scripts. */
+export function renderBackupScripts(b) {
+    return { version: '1.0\n', info: `{"online_backup":${b.online}}\n`, export: shim('export'), import: shim('import') };
+}
+export const BACKUP_SCRIPT_MODES = { version: 0o644, info: 0o644, export: 0o755, import: 0o755 };
+export function backupConfig(pkg, b) {
+    return JSON.stringify({ schema: 1, package: pkg, dataVersion: b.dataVersion, ...(b.online ? { online: true } : {}), ...(b.hook ? { hook: b.hook } : {}) }, null, 2) + '\n';
+}
+/** What sdk-package.json records, without the build-only `explicit`. */
+export function backupRecord(b) {
+    return { online: b.online, dataVersion: b.dataVersion, ...(b.hook ? { hook: b.hook } : {}) };
+}
+export function readBackupRecord(value) {
+    if (!record(value) || Object.keys(value).some(k => !['online', 'dataVersion', 'hook'].includes(k)) || typeof value.online !== 'boolean' ||
+        typeof value.dataVersion !== 'string' || !DATA_VERSION.test(value.dataVersion) || (value.hook !== undefined && !relativeExec(value.hook)))
+        return undefined;
+    return backupRecord(value);
+}
+/**
+ * Builds the SDK backup control. An SDK release without it skips the default
+ * with a warning; an explicit `backup` declaration then fails.
+ */
+/** The Go package of the SDK backup control; tests use it to tell its build apart. */
+export const APP_BACKUP_CONTROL_PACKAGE = './appbackup/cmd/control';
+export async function buildAppBackup(m, arch, work, run, warn) {
+    if (!m.hyperBackup)
+        return;
+    const source = sdkSource(daemonSdkVersion(m));
+    if (!existsSync(join(source.goDir, 'appbackup/cmd/control/main.go'))) {
+        const message = 'The selected SDK has no Hyper Backup application backup; use an SDK release with appbackup.';
+        if (m.hyperBackup.explicit)
+            throw new StandaloneBuildError('SDK_APP_BACKUP_UNSUPPORTED', message);
+        warn(`SDK_APP_BACKUP_UNSUPPORTED ${message} The package is built without application backup.`);
+        return;
+    }
+    const out = join(work, `app-backup-${arch}`);
+    const result = await run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', out, APP_BACKUP_CONTROL_PACKAGE], { cwd: source.goDir, env: goChildEnv({ ...process.env, ...pinnedGoBuildEnv(arch) }) });
+    if (result.missing && !m.hyperBackup.explicit) {
+        warn('SDK_APP_BACKUP_BUILD_FAILED Go was not found, so the package is built without application backup; install Go to include it.');
+        return;
+    }
+    if (result.status !== 0)
+        throw new StandaloneBuildError('SDK_APP_BACKUP_BUILD_FAILED', `Cannot build the SDK backup control: ${result.stderr}`);
+    const error = checkCgiBinary(work, out, arch), toolchain = pinnedGoProblem(out);
+    if (error || toolchain)
+        throw new StandaloneBuildError('SDK_APP_BACKUP_BUILD_FAILED', error?.message ?? toolchain);
+    return out;
+}
+/** The hook must be a packaged executable. */
+export function backupHookProblem(payload, b) {
+    if (!b.hook)
+        return;
+    const path = join(payload, b.hook);
+    try {
+        const s = lstatSync(path);
+        if (s.isFile() && (s.mode & 0o111) !== 0)
+            return;
+    }
+    catch { /* reported below */ }
+    return `backup.hook ${b.hook} is not an executable file in the package.`;
+}
+/**
+ * Inspect: the record, scripts/backup and payload backup/ must be exactly
+ * what build writes, or all absent. Any other file in scripts/backup — such
+ * as can_export or info.dynamic, which Hyper Backup runs as root while it only
+ * lists applications — is refused. The extracted scripts/backup is removed
+ * afterwards so later script checks see the lifecycle scripts alone.
+ */
+export async function inspectHyperBackup(dir, payloadDir, payload, raw, pkg, arch, findings) {
+    const fail = (m) => { findings.push(`BACKUP_INVALID ${m}`); };
+    const scripts = join(dir, BACKUP_SCRIPTS_DIR);
+    const present = payload.filter(p => p.path.startsWith(`${BACKUP_PAYLOAD_DIR}/`));
+    const b = raw === undefined ? undefined : readBackupRecord(raw);
+    if (raw !== undefined && !b)
+        fail('the hyperBackup record in sdk-package.json is not the one synopkgland build writes');
+    if (!b) {
+        if (lstatExists(scripts))
+            fail('scripts/backup is present without a backup declaration');
+        if (present.length)
+            fail('the payload has a backup folder without a backup declaration');
+        rmSync(scripts, { recursive: true, force: true });
+        return undefined;
+    }
+    const expected = renderBackupScripts(b);
+    const names = lstatExists(scripts) && lstatSync(scripts).isDirectory() ? readdirSync(scripts).sort() : [];
+    if (names.join() !== Object.keys(expected).sort().join())
+        fail(`scripts/backup must hold exactly export, import, info and version, found: ${names.join(', ') || 'none'}`);
+    for (const [name, text] of Object.entries(expected)) {
+        const path = join(scripts, name);
+        let s;
+        try {
+            s = lstatSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (!s.isFile() || (s.mode & 0o777) !== BACKUP_SCRIPT_MODES[name] || readFileSync(path, 'utf8') !== text)
+            fail(`scripts/backup/${name} differs from the fixed script synopkgland build writes`);
+    }
+    const files = present.map(p => `${p.path}:${p.mode}`).sort();
+    const wanted = [`${BACKUP_PAYLOAD_DIR}/config.json:0644`, `${BACKUP_PAYLOAD_DIR}/control:0755`];
+    if (files.join() !== wanted.join())
+        fail('the payload backup folder must hold exactly the SDK control and config.json');
+    else {
+        const root = await payloadDir();
+        if (readFileSync(join(root, BACKUP_PAYLOAD_DIR, 'config.json'), 'utf8') !== backupConfig(pkg, b))
+            fail('backup/config.json differs from the backup declaration');
+        const error = checkCgiBinary(root, join(root, BACKUP_PAYLOAD_DIR, 'control'), arch);
+        if (error)
+            fail(error.message);
+    }
+    rmSync(scripts, { recursive: true, force: true });
+    return b;
+}
+function lstatExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/standalone/inspect-spk.d.ts

@@ -3,12 +3,15 @@ import { type WebLaunchMode } from "../contract/web-launch.js";
 import { type ComposeApp } from "./compose.js";
 import { type ExecutorInspection } from "../runtime/executor-inspect.js";
 import { type AppScriptName } from "./app-scripts.js";
+import { type HyperBackup } from "./hyper-backup.js";
 import { type GatewayAdmissionReport } from "./identity-gateway.js";
 import type { EntryMode } from "./manifest.js";
 import { type UninstallCleanupItem } from "../runtime/uninstall-cleanup.js";
 export type SpkKind = "native-go" | "native-python" | "native-node" | "native-rust" | "binary" | "container" | "native-layout";
 export interface SpkInspection {
     installSettings?: InstallSettings;
+    /** Hyper Backup application backup, as sdk-package.json records it. */
+    hyperBackup?: HyperBackup;
     identityGateway?: GatewayAdmissionReport;
     kind?: SpkKind;
     package?: string;

package/dist/standalone/inspect-spk.js

@@ -15,6 +15,7 @@ import { checkBridgeApp, checkBridgeExecutor } from "./inspect-bridge.js";
 import { inspectExecutor, inspectExecutorAnchor, } from "../runtime/executor-inspect.js";
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { sdkScriptOf, unwrapAppScripts } from "./app-scripts.js";
+import { inspectHyperBackup } from "./hyper-backup.js";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as tar from "tar";
@@ -140,11 +141,21 @@ export async function inspectSpk(spkPath, expectedKind) {
         const identityGateway = await inspectProviderOnlyAdmission(dir, paths, metadata.provider_only_oidc, findings);
         await inspectExternalGateway(dir, paths, payload, metadata.gateway_external, findings);
         const installSettings = await inspectInstallSettings(dir, payload, metadata, findings);
+        const hyperBackup = metadataText === undefined ? undefined : await inspectHyperBackup(dir, async () => {
+            const root = join(dir, "backup-inspection");
+            if (!existsSync(root)) {
+                mkdirSync(root);
+                await tar.x({ file: join(dir, "package.tgz"), cwd: root });
+            }
+            return root;
+        }, payload, metadata.hyperBackup, /^package="([^"]*)"$/m.exec(readOptional(join(dir, "INFO")) ?? "")?.[1] ?? "", familyOfArchToken(/^arch="([^"]*)"$/m.exec(readOptional(join(dir, "INFO")) ?? "")?.[1]?.split(/\s+/)[0] ?? "") ?? "x86_64", findings);
         const integrations = metadata.integrations ?? [];
         if (metadata.compose !== undefined) {
             const result = await inspectUnifiedCompose(dir, payload, { ...metadata, installSettings }, findings);
             if (installSettings)
                 result.installSettings = installSettings;
+            if (hyperBackup)
+                result.hyperBackup = hyperBackup;
             if (identityGateway)
                 result.identityGateway = identityGateway;
             result.icon = inspectPackageIcons(dir, findings);
@@ -307,6 +318,7 @@ export async function inspectSpk(spkPath, expectedKind) {
             kind,
             ...(identityGateway ? { identityGateway } : {}),
             ...(installSettings ? { installSettings } : {}),
+            ...(hyperBackup ? { hyperBackup } : {}),
             ...(launch ? { launch } : {}),
             icon,
             ...(executor ? { executor } : {}),

package/dist/standalone/manifest.d.ts

@@ -13,6 +13,7 @@ import { type ComposeApp } from "./compose.js";
 import { type Daemon } from "./daemon.js";
 import { type IdentityGateway } from "./identity-gateway.js";
 import { type Uninstall } from "./uninstall.js";
+import { type HyperBackup } from "./hyper-backup.js";
 import { type AppScriptName } from "./app-scripts.js";
 import { type Background } from "./background.js";
 import { type SharedFolder } from "./shared-folder.js";
@@ -96,6 +97,8 @@ export interface StandaloneManifest {
     /** `install.sharedFolder`: the Shared Folder the install wizard selects or `data-share` creates. */
     sharedFolder?: SharedFolder;
     installSettings?: InstallSettings;
+    /** `backup`: Hyper Backup application backup; on by default for native Apps, absent when opted out. */
+    hyperBackup?: HyperBackup;
     /** Who may use the app at all; absent keeps the route policy alone. */
     entry?: EntryMode;
     /**

package/dist/standalone/manifest.js

@@ -17,6 +17,7 @@ import { daemonRestartSdkProblem } from "./daemon-restart.js";
 import { daemonIngressMinDsmProblem } from "./daemon-ingress.js";
 import { readIdentityGateway, } from "./identity-gateway.js";
 import { readUninstall } from "./uninstall.js";
+import { readHyperBackup } from "./hyper-backup.js";
 import { readAppScripts } from "./app-scripts.js";
 import { readBackground } from "./background.js";
 import { DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_EXECUTOR_MIN_DSM, portalByExecutor, portalMinDsmMessage, } from "../build-spk/dsm-version.js";
@@ -58,6 +59,7 @@ export const KNOWN_FIELDS = new Set([
     "compose",
     "install",
     "uninstall",
+    "backup",
     "entry",
     "integrations",
     "portal",
@@ -254,6 +256,7 @@ function readManifest(raw, c) {
         ? undefined
         : readSharedFolder(raw.install, (e) => c.fail(e.code, e.message));
     const installSettings = readInstallSettings(isRecord(raw.install) ? raw.install.settings : undefined, e => c.fail(e.code, e.message));
+    const hyperBackup = readHyperBackup(raw.backup, { compose: raw.compose !== undefined }, e => c.fail(e.code, e.message));
     const compose = arches &&
         readComposeApp(raw.compose, c.root, arches, (e) => c.fail(e.code, e.message), {
             package: packageId,
@@ -510,6 +513,7 @@ function readManifest(raw, c) {
         ...(uninstall ? { uninstall } : {}),
         ...(sharedFolder ? { sharedFolder } : {}),
         ...(installSettings ? { installSettings } : {}),
+        ...(hyperBackup ? { hyperBackup } : {}),
         ...(entry ? { entry } : {}),
         ...(integrations?.length ? { integrations } : {}),
         ...(portal ? { portal } : {}),

package/dist/standalone/spk.d.ts

@@ -18,6 +18,8 @@ export interface AssembleOptions {
     composeControl?: string;
     composeStorageInit?: string;
     installSettingsControl?: string;
+    /** The SDK backup control; absent builds without Hyper Backup application backup. */
+    appBackupControl?: string;
     /** The SDK identity gateway, required exactly when the manifest declares identity_gateway. */
     identityGateway?: string;
     /** The compiled background worker, required exactly when capabilities.jobs is enabled. */

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";
@@ -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,7 @@ 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 } : {}),
@@ -283,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.36.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

@@ -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/App 0.34.0 and CLI 0.36.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
@@ -91,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 |