@synopackageland/cli 0.4.1 → 0.5.3

package/dist/standalone/lifecycle.js

@@ -1,10 +1,20 @@
+import { hasHelper } from "./helper-inventory.js";
 import { renderHelperStoppedCheck } from "./lifecycle-helper.js";
-/** Non-privileged hooks: precheck gates DSM management; no hook tears down root. */
+import { renderBackgroundControl } from "./background.js";
+import { renderPackagePostuninst } from "../build-spk/native-lifecycle.js";
+import { renderSharedFolderScript } from "./shared-folder.js";
+/** Package-UID hooks: root auth withdraws via the trusted socket, then retains the stopped veto. */
 export function renderStandaloneScript(name, manifest) {
+    if (name === "postuninst")
+        return renderPackagePostuninst(manifest.package);
+    if (manifest.sharedFolder && (name === "postinst" || name === "postupgrade"))
+        return renderSharedFolderScript(manifest.package, manifest.sharedFolder);
     if (manifest.daemon)
         return renderDaemonScript(name, manifest);
-    if (manifest.integration && ["preupgrade", "preuninst", "start-stop-status"].includes(name)) {
-        const check = renderHelperStoppedCheck(manifest.package);
+    if (manifest.background && name === "start-stop-status")
+        return renderBackgroundControl(manifest.package);
+    if (hasHelper(manifest) && ["preupgrade", "preuninst", "start-stop-status"].includes(name)) {
+        const check = renderHelperStoppedCheck(manifest.package, manifest.privilege === 'root');
         if (name !== "start-stop-status")
             return `#!/bin/sh\n${check}`;
         return `#!/bin/sh
@@ -34,7 +44,7 @@ function renderDaemonScript(name, manifest) {
     const pkg = manifest.package;
     const control = `"/var/packages/${pkg}/target/daemon/control"`;
     const paths = `"\${SYNOPKG_PKGDEST:-/var/packages/${pkg}/target}" "\${SYNOPKG_PKGVAR:-/var/packages/${pkg}/var}"`;
-    const check = manifest.integration ? renderHelperStoppedCheck(pkg) : "";
+    const check = hasHelper(manifest) ? renderHelperStoppedCheck(pkg, manifest.privilege === 'root') : "";
     if (["preupgrade", "preuninst"].includes(name))
         return `#!/bin/sh\n${check}exec ${control} ${name === "preuninst" && manifest.daemon?.uninstall_args ? "uninstall" : "stop"} ${paths}\n`;
     if (name !== "start-stop-status")

package/dist/standalone/manifest.d.ts

@@ -3,6 +3,8 @@ import { type Catalogs, type Locale } from "./i18n.js";
 import { type RootOp } from "./root-ops.js";
 import { type Integration } from "./helper.js";
 import { type Daemon } from "./daemon.js";
+import { type Background } from "./background.js";
+import { type SharedFolder } from "./shared-folder.js";
 /**
  * `dsm-package.yaml`: a Standalone Package, i.e. an unsigned native SPK that
  * runs as its own DSM package account with a CGI backend and a DSM window UI.
@@ -47,12 +49,23 @@ export interface StandaloneManifest {
         };
     };
     i18n?: StandaloneI18n;
-    /** `none`: the package account only. `root`: adds DSM-approved root tasks. */
+    /**
+     * `none`: the package account only; an integration then has no helper.
+     * `root`: adds DSM-approved root tasks and, with an integration, its helper.
+     */
     privilege: "none" | "root";
-    /** `root/<name>.sh`, present exactly when privilege is root. */
+    /** `root/<name>.sh`, present exactly when privilege is root (empty for a helper-only integration). */
     rootOps?: RootOp[];
     integration?: Integration;
     daemon?: Daemon;
+    background?: Background;
+    /**
+     * `session`: the package account serves the interactive File Station routes
+     * through each caller's own DSM session. No helper, no stored credential.
+     */
+    fileStation?: "session";
+    /** `install.sharedFolder`: the Shared Folder the install wizard selects or `data-share` creates. */
+    sharedFolder?: SharedFolder;
 }
 export interface StandaloneError {
     code: string;

package/dist/standalone/manifest.js

@@ -5,7 +5,11 @@ import { isNativeArchFamily } from "../build-spk/dsm-arch.js";
 import { checkGlossary, isLocale, loadCatalogs } from "./i18n.js";
 import { loadRootOps, ROOT_OPS_DIR } from "./root-ops.js";
 import { readIntegration } from "./helper.js";
+import { hasHelper } from "./helper-inventory.js";
 import { readDaemon } from "./daemon.js";
+import { readBackground } from "./background.js";
+import { DEFAULT_MIN_DSM, isDsmAtLeast } from "../build-spk/dsm-version.js";
+import { readSharedFolder } from "./shared-folder.js";
 /**
  * `dsm-package.yaml`: a Standalone Package, i.e. an unsigned native SPK that
  * runs as its own DSM package account with a CGI backend and a DSM window UI.
@@ -13,7 +17,7 @@ import { readDaemon } from "./daemon.js";
 export const STANDALONE_MANIFEST = "dsm-package.yaml";
 const KNOWN_FIELDS = new Set([
     "schema", "package", "version", "build", "displayname", "description",
-    "maintainer", "os_min_ver", "arches", "backend", "ui", "privilege", "i18n", "integration", "daemon",
+    "maintainer", "os_min_ver", "arches", "backend", "ui", "privilege", "i18n", "integration", "daemon", "background", "fileStation", "install",
 ]);
 const I18N_FIELDS = new Set(["messages", "glossary", "info"]);
 const INFO_TEXT_FIELDS = new Set(["displayname", "description"]);
@@ -85,7 +89,8 @@ function readManifest(raw, c) {
     const privilege = raw.privilege === "none" || raw.privilege === "root"
         ? raw.privilege
         : c.fail("STANDALONE_PRIVILEGE_UNSUPPORTED", "privilege 只接受 none（只用套件帳號）或 root（由 DSM 管理員核准的 root 工作）；請見 README「Root access」。");
-    const rootOps = privilege && readRootOps(privilege, c);
+    const integration = readIntegration(raw.integration, c.root, e => c.fail(e.code, e.message));
+    const rootOps = privilege && readRootOps(privilege, integration !== undefined, c);
     const packageId = typeof raw.package === "string" && PACKAGE_ID.test(raw.package)
         ? raw.package
         : c.fail("STANDALONE_PACKAGE_INVALID", "package 必須以英文字母開頭，只含英數字（2–64 字）。");
@@ -98,16 +103,24 @@ function readManifest(raw, c) {
     const osMinVer = typeof raw.os_min_ver === "string" && OS_MIN_VER.test(raw.os_min_ver)
         ? raw.os_min_ver
         : c.fail("STANDALONE_OS_MIN_VER_INVALID", "os_min_ver 格式為 <major>.<minor>-<build>，例如 7.2-64570。");
+    if (privilege === "root" && osMinVer && !isDsmAtLeast(osMinVer, DEFAULT_MIN_DSM)) {
+        c.fail("STANDALONE_OS_MIN_VER_INVALID", `root templates require DSM ${DEFAULT_MIN_DSM} or later.`);
+    }
     const displayname = c.text(raw.displayname, "displayname");
     const description = c.text(raw.description, "description");
     const maintainer = c.text(raw.maintainer, "maintainer");
     const arches = readArches(raw.arches, c);
     const backend = arches && readBackend(raw.backend, arches, c);
     const daemon = arches && readDaemon(raw.daemon, c.root, arches, e => c.fail(e.code, e.message));
-    const integration = readIntegration(raw.integration, c.root, e => c.fail(e.code, e.message));
-    if (integration && (privilege !== "root" || backend?.kind !== "go" || rootOps?.some(op => op.name.startsWith("helper_")))) {
-        c.fail("STANDALONE_INTEGRATION_INVALID", "integration 需要 privilege: root 和 backend.go；helper_ 操作名稱保留給 generator。");
+    if (integration && (backend?.kind !== "go" || rootOps?.some(op => op.name.startsWith("helper_")) || (privilege === "none" && !isPackageOnly(integration)))) {
+        c.fail("STANDALONE_INTEGRATION_INVALID", "integration 需要 backend.go；helper_ 操作名稱保留給 generator。privilege: none 只提供套件帳號整合（protocol 1、workers 為空，可選 identity），helper 設定需要 privilege: root。");
+    }
+    const background = readBackground(raw.background, e => c.fail(e.code, e.message));
+    if (raw.background !== undefined && (backend?.kind !== "go" || raw.daemon !== undefined || privilege === "root")) {
+        c.fail("STANDALONE_BACKGROUND_INVALID", "background 需要 backend.go（worker 由專案的 Go module 編譯）與 privilege: none，且不能與 daemon 並用；套件帳號 integration 可並用，root helper 不行。");
     }
+    const fileStation = raw.fileStation === undefined ? undefined : readFileStation(raw.fileStation, backend?.kind === "go" && !hasHelper({ integration, privilege }), c);
+    const sharedFolder = raw.install === undefined ? undefined : readSharedFolder(raw.install, e => c.fail(e.code, e.message));
     const ui = readUi(raw.ui, c);
     const i18n = raw.i18n === undefined ? undefined : readI18n(raw.i18n, c);
     if (!packageId || !version || !build || !osMinVer || !displayname || !description || !maintainer
@@ -132,15 +145,27 @@ function readManifest(raw, c) {
         ...(rootOps ? { rootOps } : {}),
         ...(integration ? { integration } : {}),
         ...(daemon ? { daemon } : {}),
+        ...(background ? { background } : {}),
+        ...(fileStation ? { fileStation } : {}),
+        ...(sharedFolder ? { sharedFolder } : {}),
     };
 }
-function readRootOps(privilege, c) {
+/** Without privilege: root there is no helper, so none of its inventory settings apply. */
+function isPackageOnly(integration) {
+    return integration.protocol === 1 && Object.keys(integration.workers).length === 0
+        && integration.dataAccess === undefined && integration.sdkWorkers === undefined;
+}
+/** A root integration's helper tasks are generated; it needs no root/ operation of its own. */
+function readRootOps(privilege, hasIntegration, c) {
     const dir = join(c.root, ROOT_OPS_DIR);
     if (privilege === "none") {
         return existsSync(dir)
             ? c.fail("STANDALONE_ROOT_OPS_UNUSED", `${ROOT_OPS_DIR}/ 只用在 privilege: root；privilege: none 的套件不會執行它。`)
             : undefined;
     }
+    if (hasIntegration && !existsSync(dir)) {
+        return [];
+    }
     const loaded = loadRootOps(dir);
     if (!loaded.ok) {
         loaded.errors.forEach((e) => c.fail(e.code, e.message));
@@ -277,3 +302,9 @@ export function findStandaloneRoot(start) {
         current = parent;
     }
 }
+function readFileStation(value, allowed, c) {
+    if (value === "session" && allowed)
+        return "session";
+    c.fail("STANDALONE_FILESTATION_INVALID", "fileStation 只接受 session，需要 backend.go，且不能與 root helper integration 並用（helper 有自己的 File Station gate）。");
+    return undefined;
+}

package/dist/standalone/native-layout.d.ts

@@ -0,0 +1,74 @@
+import type { CommandRunner } from './build.js';
+export declare const LAYOUT_ARCHES: {
+    readonly x86_64: readonly [2, 62];
+    readonly aarch64: readonly [2, 183];
+    readonly armv8: readonly [2, 183];
+    readonly armv7: readonly [1, 40];
+};
+export type LayoutArch = keyof typeof LAYOUT_ARCHES;
+type Hook = {
+    command: string[];
+    cwd: string;
+    env: Record<string, string>;
+};
+type Toolkit = {
+    url: string;
+    sha256: string;
+};
+type Binary = {
+    path: string;
+    linkage: 'static' | 'dynamic';
+    arches?: LayoutArch[];
+};
+export interface NativeLayout {
+    root: string;
+    package: string;
+    version: string;
+    build: number;
+    displayname: string;
+    description: string;
+    maintainer: string;
+    os_min_ver: string;
+    privilege: 'none';
+    arches: LayoutArch[];
+    layout: {
+        payload: string;
+        metadata: string;
+        binaries: Binary[];
+    };
+    native: {
+        prepare?: Hook;
+        hook: Hook;
+        toolkits: Partial<Record<LayoutArch, Toolkit[]>>;
+    };
+}
+export declare function isNativeLayout(root: string): boolean;
+export declare function loadNativeLayout(root: string): {
+    ok: true;
+    manifest: NativeLayout;
+} | {
+    ok: false;
+    errors: {
+        code: string;
+        message: string;
+    }[];
+};
+export declare function verifyToolkitArchive(path: string, expected: string): void;
+export declare function layoutFiles(root: string): Array<{
+    path: string;
+    mode: number;
+    sha256: string;
+}>;
+export declare function checkLayoutBinary(root: string, b: Binary, arch: LayoutArch): void;
+export declare function checkLayoutMetadata(root: string, inspection?: boolean, packageId?: string): void;
+export declare function buildNativeLayout(options: {
+    root: string;
+    arches?: string[];
+    outDir?: string;
+    build?: number;
+    run?: CommandRunner;
+}): Promise<{
+    outputs: string[];
+}>;
+export declare function inspectNativeLayout(dir: string, payload: string, info: Record<string, string>): string[];
+export {};

package/dist/standalone/native-layout.js

@@ -0,0 +1,318 @@
+/** Existing native products: the CLI owns archives/INFO, the project owns its layout. */
+import { createHash } from 'node:crypto';
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { parse } from 'yaml';
+import { createReproducibleTar } from '../build-spk/reproducible-archive.js';
+import { runCommand } from './build.js';
+export const LAYOUT_ARCHES = { x86_64: [2, 62], aarch64: [2, 183], armv8: [2, 183], armv7: [1, 40] };
+function fail(message) { throw new Error(`NATIVE_LAYOUT_INVALID: ${message}`); }
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function object(value, fields) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail('expected object');
+    const obj = value;
+    if (Object.keys(obj).some(k => !fields.includes(k)))
+        fail('unknown field');
+    return obj;
+}
+function text(value) {
+    if (typeof value !== 'string' || !value || /[\r\n"\\\0]/.test(value))
+        fail('invalid text');
+    return value;
+}
+function pathText(value) {
+    const path = text(value);
+    if (isAbsolute(path) || path.split('/').some(p => p === '..' || p === '') || /[{}]/.test(path.replaceAll('{arch}', '')))
+        fail('path must stay inside project');
+    return path;
+}
+function inside(root, path) {
+    const full = resolve(root, path);
+    const rel = relative(realpathSync(root), realpathSync(full));
+    if (rel === '..' || rel.startsWith('../') || isAbsolute(rel))
+        fail('path escapes project');
+    return full;
+}
+function hook(value) {
+    const h = object(value, ['command', 'cwd', 'env']);
+    if (!Array.isArray(h.command) || !h.command.length || !h.command.every((x) => typeof x === 'string' && x.length > 0 && !x.includes('\0')))
+        fail('hook requires argv');
+    const env = object(h.env ?? {}, Object.keys(h.env ?? {}));
+    for (const [key, value] of Object.entries(env))
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(key) || typeof value !== 'string' || value.includes('\0') || key.startsWith('SYNOPKGLAND_'))
+            fail('invalid hook environment');
+    return { command: h.command, cwd: pathText(h.cwd ?? '.'), env };
+}
+export function isNativeLayout(root) {
+    try {
+        return parse(readFileSync(join(root, 'dsm-package.yaml'), 'utf8'))?.layout !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+export function loadNativeLayout(root) {
+    try {
+        const m = object(parse(readFileSync(join(root, 'dsm-package.yaml'), 'utf8')), ['schema', 'package', 'version', 'build', 'displayname', 'description', 'maintainer', 'os_min_ver', 'privilege', 'arches', 'layout', 'native']);
+        if (m.schema !== 1 || m.privilege !== 'none')
+            fail('schema 1 and privilege: none required');
+        if (!/^[A-Za-z][A-Za-z0-9]{1,63}$/.test(text(m.package)) || !/^\d+(\.\d+){0,3}$/.test(text(m.version)) || !/^7\.\d+(\.\d+)?-\d+$/.test(text(m.os_min_ver)))
+            fail('invalid package/version/DSM');
+        if (!Number.isSafeInteger(m.build) || m.build < 1 || m.build > 2147483647)
+            fail('build must be 1..2147483647');
+        for (const k of ['displayname', 'description', 'maintainer'])
+            text(m[k]);
+        if (!Array.isArray(m.arches) || !m.arches.length || new Set(m.arches).size !== m.arches.length || m.arches.some((a) => !Object.hasOwn(LAYOUT_ARCHES, a)))
+            fail('invalid architecture list');
+        const layout = object(m.layout, ['payload', 'metadata', 'binaries']);
+        layout.payload = pathText(layout.payload);
+        layout.metadata = pathText(layout.metadata);
+        if (!Array.isArray(layout.binaries) || !layout.binaries.length)
+            fail('binary assertions required');
+        for (const b of layout.binaries) {
+            object(b, ['path', 'linkage', 'arches']);
+            pathText(b.path);
+            if (!['static', 'dynamic'].includes(b.linkage))
+                fail('declare binary linkage');
+            if (b.arches !== undefined && (!Array.isArray(b.arches) || !b.arches.length || b.arches.some((a) => !m.arches.includes(a))))
+                fail('invalid binary arches');
+        }
+        const native = object(m.native, ['prepare', 'hook', 'toolkits']);
+        const toolkits = object(native.toolkits ?? {}, m.arches);
+        for (const entries of Object.values(toolkits)) {
+            if (!Array.isArray(entries) || !entries.length)
+                fail('toolkits require archives');
+            for (const t of entries) {
+                object(t, ['url', 'sha256']);
+                const u = new URL(t.url);
+                if (u.protocol !== 'https:' || u.username || u.password || !/^[a-f0-9]{64}$/.test(t.sha256))
+                    fail('toolkits require HTTPS and SHA-256');
+            }
+        }
+        return { ok: true, manifest: { ...m, root: resolve(root), native: { hook: hook(native.hook), ...(native.prepare ? { prepare: hook(native.prepare) } : {}), toolkits } } };
+    }
+    catch (error) {
+        return { ok: false, errors: [{ code: 'NATIVE_LAYOUT_INVALID', message: String(error) }] };
+    }
+}
+export function verifyToolkitArchive(path, expected) {
+    if (!lstatSync(path).isFile() || digest(readFileSync(path)) !== expected)
+        fail('toolkit checksum mismatch');
+}
+async function toolkitFor(m, arch, run) {
+    const inputs = m.native.toolkits[arch] ?? [];
+    if (!inputs.length)
+        return '';
+    const cache = resolve(process.env.SYNOPKGLAND_CACHE_DIR ?? join(m.root, '.synopkgland-cache'));
+    mkdirSync(cache, { recursive: true, mode: 0o700 });
+    if (lstatSync(cache).isSymbolicLink() || (lstatSync(cache).mode & 0o022))
+        fail('toolkit cache must be owned and private');
+    const archives = [];
+    for (const input of inputs) {
+        const archive = join(cache, `${input.sha256}.txz`);
+        if (!existsSync(archive)) {
+            const download = mkdtempSync(join(cache, '.download-'));
+            try {
+                const out = join(download, 'archive');
+                const r = run('curl', ['--fail', '--location', '--proto', '=https', '--proto-redir', '=https', '--retry', '2', '--retry-all-errors', '--connect-timeout', '20', '--max-time', '600', '--output', out, input.url], { cwd: m.root, env: { ...process.env } });
+                if (r.status !== 0)
+                    fail('toolkit download failed');
+                verifyToolkitArchive(out, input.sha256);
+                renameSync(out, archive);
+            }
+            finally {
+                rmSync(download, { recursive: true, force: true });
+            }
+        }
+        verifyToolkitArchive(archive, input.sha256);
+        archives.push(archive);
+    }
+    // Re-extract verified bytes: a package-writable marker never authenticates an extracted tree.
+    const stage = mkdtempSync(join(cache, `toolkit-${arch}-`));
+    try {
+        for (const archive of archives) {
+            const r = run('tar', ['-xJf', archive, '-C', stage, '--keep-directory-symlink'], { cwd: m.root, env: { ...process.env } });
+            if (r.status !== 0)
+                fail('toolkit extraction failed');
+        }
+        return stage;
+    }
+    catch (e) {
+        rmSync(stage, { recursive: true, force: true });
+        throw e;
+    }
+}
+function runHook(m, h, env, run) {
+    const [cmd, ...args] = h.command;
+    const r = run(cmd, args, { cwd: inside(m.root, h.cwd), env: { ...process.env, ...h.env, ...env } });
+    if (r.status !== 0 || r.missing)
+        fail(`native hook failed: ${r.stderr}`);
+}
+export function layoutFiles(root) {
+    if (!lstatSync(root).isDirectory() || lstatSync(root).isSymbolicLink())
+        fail('layout root must be a regular directory');
+    const files = [];
+    let total = 0;
+    const walk = (prefix) => {
+        for (const name of readdirSync(join(root, prefix)).sort()) {
+            const path = prefix ? `${prefix}/${name}` : name;
+            const s = lstatSync(join(root, path));
+            if (s.isSymbolicLink() || (!s.isFile() && !s.isDirectory()))
+                fail('layout contains symlink or special file');
+            if (s.mode & 0o6000)
+                fail('privileged file modes are forbidden');
+            if (s.isDirectory())
+                walk(path);
+            else {
+                total += s.size;
+                if (s.size > 256 * 1024 * 1024 || total > 1024 * 1024 * 1024)
+                    fail('layout exceeds size bound');
+                files.push({ path, mode: s.mode & 0o111 ? 0o755 : 0o644, sha256: digest(readFileSync(join(root, path))) });
+            }
+        }
+    };
+    walk('');
+    return files;
+}
+export function checkLayoutBinary(root, b, arch) {
+    const path = inside(root, b.path);
+    const bytes = readFileSync(path);
+    const [cls, machine] = LAYOUT_ARCHES[arch];
+    if (bytes.length < 64 || bytes.toString('latin1', 0, 4) !== '\x7fELF' || bytes[4] !== cls || bytes[5] !== 1 || bytes.readUInt16LE(18) !== machine || ![2, 3].includes(bytes.readUInt16LE(16)))
+        fail(`ELF architecture mismatch: ${b.path}`);
+    const offset = cls === 1 ? bytes.readUInt32LE(28) : Number(bytes.readBigUInt64LE(32));
+    const size = bytes.readUInt16LE(cls === 1 ? 42 : 54);
+    const count = bytes.readUInt16LE(cls === 1 ? 44 : 56);
+    if (!count || size < (cls === 1 ? 32 : 56) || !Number.isSafeInteger(offset) || offset + size * count > bytes.length)
+        fail('invalid ELF program headers');
+    let dynamic = false;
+    for (let i = 0; i < count; i++)
+        if (bytes.readUInt32LE(offset + size * i) === 3)
+            dynamic = true;
+    if (dynamic !== (b.linkage === 'dynamic'))
+        fail(`ELF linkage mismatch: ${b.path}`);
+    if (!(lstatSync(path).mode & 0o111))
+        fail(`binary must be executable: ${b.path}`);
+}
+function copyTree(from, to) {
+    const entries = layoutFiles(from);
+    for (const entry of entries) {
+        const out = join(to, entry.path);
+        mkdirSync(dirname(out), { recursive: true });
+        copyFileSync(join(from, entry.path), out);
+        chmodSync(out, entry.mode);
+    }
+    return entries;
+}
+export function checkLayoutMetadata(root, inspection = false, packageId) {
+    const p = JSON.parse(readFileSync(join(root, 'conf/privilege'), 'utf8'));
+    if (p.defaults?.['run-as'] !== 'package' || Object.keys(p).some(k => !['defaults', 'username', 'groupname'].includes(k)) || ['username', 'groupname'].some(k => p[k] !== undefined && p[k] !== packageId) || Object.keys(p.defaults).some(k => k !== 'run-as'))
+        fail('native layout requires package-only lifecycle privilege');
+    if (!existsSync(join(root, 'scripts/start-stop-status')))
+        fail('start-stop-status missing');
+    if (existsSync(join(root, 'conf/resource'))) {
+        const resource = object(JSON.parse(readFileSync(join(root, 'conf/resource'), 'utf8')), ['systemd-unit']);
+        if (resource['systemd-unit'] !== undefined && Object.keys(object(resource['systemd-unit'], [])).length)
+            fail('unsupported resource worker');
+    }
+    if (existsSync(join(root, 'conf/systemd'))) {
+        for (const entry of layoutFiles(join(root, 'conf/systemd'))) {
+            const unit = readFileSync(join(root, 'conf/systemd', entry.path), 'utf8');
+            const users = [...unit.matchAll(/^\s*User\s*=\s*(.*?)\s*$/gm)].map(m => m[1]);
+            const groups = [...unit.matchAll(/^\s*Group\s*=\s*(.*?)\s*$/gm)].map(m => m[1]);
+            if (!packageId || users.length !== 1 || users[0] !== packageId || groups.some(group => group !== packageId) || /^\s*(?:AmbientCapabilities|SupplementaryGroups|PermissionsStartOnly|RootDirectory|RootImage)\s*=/m.test(unit) || /^\s*Exec\w*\s*=\s*[+!]/m.test(unit))
+                fail('systemd unit must run only as the package account');
+        }
+    }
+    for (const name of readdirSync(root))
+        if (!['conf', 'scripts', 'WIZARD_UIFILES', 'PACKAGE_ICON.PNG', 'PACKAGE_ICON_256.PNG', ...(inspection ? ['INFO', 'package.tgz', 'native-layout.json', 'layout-inspection'] : [])].includes(name))
+            fail(`unsupported SPK metadata: ${name}`);
+    for (const f of layoutFiles(root)) {
+        if (f.path.startsWith('scripts/') && /\bsudo\b|\bchown\s+root\b|chmod\s+[ugo]*\+s\b/.test(readFileSync(join(root, f.path), 'utf8')))
+            fail('root lifecycle operation forbidden');
+    }
+}
+export async function buildNativeLayout(options) {
+    const loaded = loadNativeLayout(options.root);
+    if (!loaded.ok)
+        fail(loaded.errors.map(e => e.message).join('\n'));
+    const m = loaded.manifest;
+    if (options.build !== undefined) {
+        if (!Number.isSafeInteger(options.build) || options.build < 1 || options.build > 2147483647)
+            fail('invalid build override');
+        m.build = options.build;
+    }
+    const arches = options.arches ?? m.arches;
+    if (!arches.length || new Set(arches).size !== arches.length || arches.some(a => !m.arches.includes(a)))
+        fail('architecture not declared');
+    const run = options.run ?? runCommand;
+    const version = `${m.version}-${String(m.build).padStart(4, '0')}`;
+    const env = { SYNOPKGLAND_PACKAGE: m.package, SYNOPKGLAND_VERSION: m.version, SYNOPKGLAND_BUILD: String(m.build), SYNOPKGLAND_SPK_VERSION: version, SYNOPKGLAND_PROJECT_DIR: m.root };
+    if (m.native.prepare)
+        runHook(m, m.native.prepare, env, run);
+    const outputs = [];
+    for (const requested of arches) {
+        const arch = requested;
+        const toolkit = await toolkitFor(m, arch, run);
+        const stage = mkdtempSync(join(tmpdir(), 'synopkgland-layout-'));
+        try {
+            runHook(m, m.native.hook, { ...env, SYNOPKGLAND_ARCH: arch, SYNOPKGLAND_TOOLKIT_DIR: toolkit }, run);
+            const payload = inside(m.root, m.layout.payload.replaceAll('{arch}', arch));
+            const metadata = inside(m.root, m.layout.metadata);
+            checkLayoutMetadata(metadata, false, m.package);
+            layoutFiles(payload);
+            const binaries = m.layout.binaries.filter(b => !b.arches || b.arches.includes(arch));
+            if (!binaries.length)
+                fail("binary assertions required for every architecture");
+            for (const b of binaries)
+                checkLayoutBinary(payload, b, arch);
+            copyTree(metadata, stage);
+            const target = join(stage, 'payload');
+            mkdirSync(target);
+            const files = copyTree(payload, target);
+            await createReproducibleTar(target, join(stage, 'package.tgz'), { gzip: true });
+            rmSync(target, { recursive: true });
+            const fields = { package: m.package, version, arch, os_min_ver: m.os_min_ver, displayname: m.displayname, description: m.description, maintainer: m.maintainer, dsmuidir: 'ui', dsmappname: `SYNO.SDS.${m.package}.Instance`, startable: 'yes', thirdparty: 'yes', checksum: createHash('md5').update(readFileSync(join(stage, 'package.tgz'))).digest('hex') };
+            writeFileSync(join(stage, 'INFO'), Object.entries(fields).map(([k, v]) => `${k}="${v}"\n`).join(''));
+            writeFileSync(join(stage, 'native-layout.json'), JSON.stringify({ format: 1, arch, binaries: binaries.map(({ path, linkage }) => ({ path, linkage })), files }));
+            const output = join(options.outDir ?? join(m.root, 'dist'), `${m.package}-${version}-${arch}.spk`);
+            mkdirSync(dirname(output), { recursive: true });
+            await createReproducibleTar(stage, output);
+            outputs.push(output);
+        }
+        finally {
+            rmSync(stage, { recursive: true, force: true });
+            if (toolkit)
+                rmSync(toolkit, { recursive: true, force: true });
+        }
+    }
+    return { outputs };
+}
+export function inspectNativeLayout(dir, payload, info) {
+    try {
+        const inv = object(JSON.parse(readFileSync(join(dir, 'native-layout.json'), 'utf8')), ['format', 'arch', 'binaries', 'files']);
+        if (inv.format !== 1 || inv.arch !== info.arch || !Object.hasOwn(LAYOUT_ARCHES, inv.arch))
+            fail('invalid native layout inventory');
+        checkLayoutMetadata(dir, true, info.package);
+        const actual = layoutFiles(payload);
+        if (JSON.stringify(actual) !== JSON.stringify(inv.files))
+            fail('payload checksum or mode mismatch');
+        if (!Array.isArray(inv.binaries) || !inv.binaries.length)
+            fail('missing binary assertions');
+        for (const b of inv.binaries) {
+            object(b, ['path', 'linkage']);
+            pathText(b.path);
+            if (!['static', 'dynamic'].includes(b.linkage))
+                fail('invalid linkage');
+            checkLayoutBinary(payload, b, inv.arch);
+        }
+        if (createHash('md5').update(readFileSync(join(dir, 'package.tgz'))).digest('hex') !== info.checksum)
+            fail('package checksum mismatch');
+        return [];
+    }
+    catch (e) {
+        return [String(e)];
+    }
+}

package/dist/standalone/resource.d.ts

@@ -0,0 +1,11 @@
+import type { Background } from "./background.js";
+import { type SharedFolder } from "./shared-folder.js";
+/**
+ * `conf/resource` for a native package: only DSM's official `data-share` and
+ * `systemd-user-unit` workers, in a fixed key order. Undefined when neither applies.
+ */
+export declare function renderStandaloneResource(m: {
+    package: string;
+    background?: Background;
+    sharedFolder?: SharedFolder;
+}): string | undefined;

package/dist/standalone/resource.js

@@ -0,0 +1,13 @@
+import { sharedFolderResource } from "./shared-folder.js";
+/**
+ * `conf/resource` for a native package: only DSM's official `data-share` and
+ * `systemd-user-unit` workers, in a fixed key order. Undefined when neither applies.
+ */
+export function renderStandaloneResource(m) {
+    const dataShare = m.sharedFolder && sharedFolderResource(m.package, m.sharedFolder);
+    const resource = {
+        ...(dataShare ? { "data-share": dataShare } : {}),
+        ...(m.background ? { "systemd-user-unit": {} } : {}),
+    };
+    return Object.keys(resource).length > 0 ? JSON.stringify(resource) : undefined;
+}

package/dist/standalone/root-ops.d.ts

@@ -11,6 +11,8 @@ export interface RootOp {
     body: string;
     /** Internal generator flag for protected helper control output. */
     protectedOutput?: boolean;
+    /** Bootstrap wraps public output in a protected directory without hiding it. */
+    exposeOutput?: boolean;
 }
 export type RootOpsResult = {
     ok: true;

package/dist/standalone/root-ops.js

@@ -68,6 +68,16 @@ function readRootOp(path, file) {
  */
 export function renderRootTaskScript(manifest, op) {
     const body = op.body.endsWith("\n") ? op.body : `${op.body}\n`;
+    // Wrapped helper operations expose no output; don't leave a root-owned
+    // output directory or files for an operation whose result is task history.
+    if (op.protectedOutput && op.exposeOutput === false)
+        return `${rootTaskHeader(manifest.package, op.name)}${manifest.spkVersion}.
+set -eu
+PATH=/usr/sbin:/usr/bin:/sbin:/bin
+export PATH
+/bin/sh -eu <<'${ROOT_OP_END}'
+${body}${ROOT_OP_END}
+`;
     return `${rootTaskHeader(manifest.package, op.name)}${manifest.spkVersion}.
 # Approved by a DSM administrator; runs only when this task is run.
 set -eu