@synopackageland/cli 0.1.0 → 0.2.0

package/dist/build-spk/native-payload.js

@@ -1,39 +1,15 @@
-import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import { chmodSync, closeSync, copyFileSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readlinkSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
-import { dirname, join, posix, resolve } from "node:path";
-import { inflateRawSync } from "node:zlib";
-import * as tar from "tar";
-import { collectArchiveEntries, createReproducibleTar } from "./reproducible-archive.js";
-class NativePayloadError extends Error {
-    code;
-    constructor(code, message) {
-        super(`${code}: ${message}`);
-        this.name = "NativePayloadError";
-        this.code = code;
-    }
-}
-export function archiveKindFor(nameOrUrl) {
-    const pathname = nameOrUrlForSuffix(nameOrUrl).toLowerCase();
-    if (pathname.endsWith(".tar.gz")) {
-        return "tar.gz";
-    }
-    if (pathname.endsWith(".tar.xz")) {
-        return "tar.xz";
-    }
-    if (pathname.endsWith(".zip")) {
-        return "zip";
-    }
-    return "raw";
-}
-export async function buildNativePayload(options) {
+/**
+ * Materializes one target's binary tree into `destDir`, which becomes the
+ * payload root (SYNOPKG_PKGDEST). Shared by `buildNativePayload` and by the SPK
+ * generator, which needs the tree in its own staging directory so the App
+ * Bundle files can sit alongside the binaries in a single package.tgz.
+ */
+export async function materializeNativePayload(options) {
     const stripComponents = readStripComponents(options.source.strip_components);
-    const outputPath = resolve(options.outputTgz);
-    const outputParent = dirname(outputPath);
-    mkdirSync(outputParent, { recursive: true });
-    rmSync(outputPath, { force: true });
-    const workDir = mkdtempSync(join(outputParent, ".syno-native-payload-"));
-    let committed = false;
+    const targetDir = resolve(options.destDir);
+    mkdirSync(targetDir, { recursive: true, mode: 0o755 });
+    chmodSync(targetDir, 0o755);
+    const workDir = mkdtempSync(join(dirname(targetDir), ".syno-native-extract-"));
     try {
         const sourceName = options.source.path ?? options.source.url;
         if (sourceName === undefined) {
@@ -52,9 +28,6 @@ export async function buildNativePayload(options) {
         // extracts package.tgz straight into it. Nesting a literal `target/`
         // directory here would put the binary at $SYNOPKG_PKGDEST/target/<exec>.
         // Same layout the Broker SPK ships (packages/broker/src/spk/build.ts).
-        const targetDir = join(workDir, "package");
-        mkdirSync(targetDir, { recursive: true, mode: 0o755 });
-        chmodSync(targetDir, 0o755);
         if (kind === "raw") {
             materializeRaw(sourceBytes, targetDir, rawSourceName(sourceName));
         }
@@ -81,7 +54,55 @@ export async function buildNativePayload(options) {
             validateExtractedTarTree(rawDir, descriptors, stripComponents);
             copyStrippedTree(rawDir, targetDir, stripComponents);
         }
-        const entries = collectArchiveEntries(targetDir);
+        return { sourceSha256, entries: collectArchiveEntries(targetDir) };
+    }
+    finally {
+        rmSync(workDir, { recursive: true, force: true });
+    }
+}
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, closeSync, copyFileSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readlinkSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join, posix, resolve } from "node:path";
+import { inflateRawSync } from "node:zlib";
+import * as tar from "tar";
+import { collectArchiveEntries, createReproducibleTar } from "./reproducible-archive.js";
+class NativePayloadError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.name = "NativePayloadError";
+        this.code = code;
+    }
+}
+export function archiveKindFor(nameOrUrl) {
+    const pathname = nameOrUrlForSuffix(nameOrUrl).toLowerCase();
+    if (pathname.endsWith(".tar.gz")) {
+        return "tar.gz";
+    }
+    if (pathname.endsWith(".tar.xz")) {
+        return "tar.xz";
+    }
+    if (pathname.endsWith(".zip")) {
+        return "zip";
+    }
+    return "raw";
+}
+export async function buildNativePayload(options) {
+    const outputPath = resolve(options.outputTgz);
+    const outputParent = dirname(outputPath);
+    mkdirSync(outputParent, { recursive: true });
+    rmSync(outputPath, { force: true });
+    const workDir = mkdtempSync(join(outputParent, ".syno-native-payload-"));
+    let committed = false;
+    try {
+        const { sourceSha256, entries } = await materializeNativePayload({
+            source: options.source,
+            projectRoot: options.projectRoot,
+            destDir: join(workDir, "package"),
+            download: options.download,
+        });
+        const targetDir = join(workDir, "package");
         const temporaryOutput = join(workDir, "package.tgz");
         await createReproducibleTar(targetDir, temporaryOutput, { gzip: true });
         const packageSha256 = digestFile(temporaryOutput);
@@ -119,6 +140,11 @@ async function readSourceBytes(options) {
     return bytes;
 }
 async function defaultDownload(url) {
+    if (url.startsWith("file://")) {
+        const { fileURLToPath } = await import("node:url");
+        const filePath = fileURLToPath(url);
+        return readFileSync(filePath);
+    }
     const response = await fetch(url);
     if (!response.ok) {
         throw new NativePayloadError("NATIVE_PAYLOAD_DOWNLOAD_FAILED", `HTTP ${response.status} while downloading ${url}`);

package/dist/cli.js

@@ -8,6 +8,7 @@ import { validateProject } from "./validate.js";
 import { runDev } from "./dev.js";
 import { testProject } from "./test-command.js";
 import { buildSpk } from "./build-spk/generator.js";
+import { isNativeArchFamily } from "./build-spk/dsm-arch.js";
 import { deployProject } from "./deploy/deploy.js";
 import { createNasHost } from "./host/dsm-client.js";
 import { projectInfo, formatProjectInfo } from "./info.js";
@@ -79,19 +80,29 @@ export async function runCli(argv) {
     program
         .command("init")
         .description("從模板建立 App 專案")
-        .requiredOption("-t, --template <name>", `模板：${listTemplates().join(" | ")}`)
+        .option("-t, --template <name>", `模板：${listTemplates().join(" | ")}`)
+        .option("--native", "建立 Native Prebuilt Binary App 專案")
         .argument("[dir]", "目標目錄", ".")
-        .action((dir, options, command) => {
+        .action(async (dir, options, command) => {
         const global = command.parent?.opts() ?? {};
         if (global.project) {
             console.error("--project 不適用於 init。");
             process.exit(1);
         }
+        const targetDir = resolve(process.cwd(), dir);
+        if (options.native) {
+            initFromTemplate("native", targetDir);
+            console.log(`已建立 native 專案於 ${targetDir}`);
+            return;
+        }
+        if (!options.template) {
+            console.error(`請指定 -t, --template <name> 或 --native。可選模板：${listTemplates().join(" | ")}`);
+            process.exit(1);
+        }
         if (!isTemplateName(options.template)) {
             console.error(`未知模板：${options.template}`);
             process.exit(1);
         }
-        const targetDir = resolve(process.cwd(), dir);
         initFromTemplate(options.template, targetDir);
         console.log(`已建立 ${options.template} 專案於 ${targetDir}`);
     });
@@ -173,6 +184,7 @@ export async function runCli(argv) {
         .command("deploy")
         .description("Inner Loop Deploy 到 NAS（產生 SPK、簽發 Local Attestation、安裝）")
         .requiredOption("--host <name>", "synoagentcli profile 或 NAS 名稱")
+        .option("--arch <family>", "native App 的目標架構：x86_64 或 aarch64（省略時由 NAS 判定）")
         .option("--dev", "部署到 Development Package Identity（{package}.dev）")
         .option("--replace-curated", "危險：將既有 Curated App Package Attestation 降級為 Local Attestation")
         .option("--share <slot=name>", "此 NAS 上的 Shared Folder 邏輯名（契約 shared_folder 槽，可重複）", collectShareOption)
@@ -186,7 +198,12 @@ export async function runCli(argv) {
             process.exit(1);
         }
         try {
+            if (options.arch !== undefined && !isNativeArchFamily(String(options.arch))) {
+                console.error(`--arch 只接受 x86_64 或 aarch64，收到 ${String(options.arch)}。`);
+                process.exit(1);
+            }
             const result = await deployProject({
+                archFamily: options.arch ? String(options.arch) : undefined,
                 project,
                 host,
                 dev: options.dev,
@@ -292,12 +309,18 @@ export async function runCli(argv) {
         .command("build-spk")
         .description("產生本機 thin SPK（未簽署）")
         .option("-o, --output <path>", "輸出 .spk 路徑")
+        .option("--arch <family>", "native App 的目標架構：x86_64 或 aarch64（Compose App 不需要）")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
         const project = resolveProject(process.cwd(), global.project);
+        if (options.arch !== undefined && !isNativeArchFamily(String(options.arch))) {
+            console.error(`--arch 只接受 x86_64 或 aarch64，收到 ${String(options.arch)}。`);
+            process.exit(1);
+        }
         const result = await buildSpk({
             project,
             outputPath: options.output ? resolve(process.cwd(), options.output) : undefined,
+            archFamily: options.arch ? String(options.arch) : undefined,
         });
         if (!result.ok) {
             console.error(`建置失敗：${result.errors.join(", ")}`);

package/dist/deploy/deploy.d.ts

@@ -1,8 +1,11 @@
+import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
 import type { ProjectRoot } from "../discovery.js";
 import type { NasHost } from "../host/types.js";
 import type { PublishSpkResult } from "@synopackageland/package-source/publish-spk";
 export interface DeployProjectOptions {
     project: ProjectRoot;
+    /** native App only: which target to build. Omitted means "ask the NAS". */
+    archFamily?: NativeArchFamily;
     host: NasHost;
     dev?: boolean;
     replaceCurated?: boolean;

package/dist/deploy/deploy.js

@@ -1,4 +1,5 @@
 import { buildSpk } from "../build-spk/generator.js";
+import { existsSync } from "node:fs";
 import { loadContract } from "../contract/load.js";
 import { digestProjectBundle, digestProjectContract } from "../host/digests.js";
 import { appOriginFromContract } from "../host/open-url.js";
@@ -67,11 +68,23 @@ export async function deployProject(options) {
         };
     }
     const spkVersion = await resolveDeploySpkVersion(options.project, options.host, identity.packageId);
+    let archFamily = options.archFamily;
+    if (archFamily === undefined && options.project.nativePath && existsSync(options.project.nativePath)) {
+        archFamily = await options.host.getArchFamily?.();
+        if (archFamily === undefined) {
+            return {
+                ok: false,
+                code: "NATIVE_ARCH_UNDETERMINED",
+                message: "無法從這台 NAS 判定 CPU 架構。請用 --arch x86_64 或 --arch aarch64 明確指定。",
+            };
+        }
+    }
     const build = await buildSpk({
         project: options.project,
         packageIdentity: identity.packageId,
         displayname: identity.displayname,
         spkVersion,
+        archFamily,
     });
     if (!build.ok || !build.outputPath) {
         return { ok: false, code: "BUILD_SPK_FAILED", message: build.errors.join(", ") };

package/dist/discovery.d.ts

@@ -1,8 +1,10 @@
 export declare const CONTRACT_FILENAME = "synology-app.yaml";
 export declare const COMPOSE_FILENAME = "compose.yaml";
+export declare const NATIVE_FILENAME = "native.yaml";
 export interface ProjectRoot {
     root: string;
     contractPath: string;
     composePath: string;
+    nativePath?: string;
 }
 export declare function findProjectRoot(startDir: string): ProjectRoot | null;

package/dist/discovery.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 export const CONTRACT_FILENAME = "synology-app.yaml";
 export const COMPOSE_FILENAME = "compose.yaml";
+export const NATIVE_FILENAME = "native.yaml";
 export function findProjectRoot(startDir) {
     let current = resolve(startDir);
     while (true) {
@@ -11,6 +12,7 @@ export function findProjectRoot(startDir) {
                 root: current,
                 contractPath,
                 composePath: join(current, COMPOSE_FILENAME),
+                nativePath: join(current, NATIVE_FILENAME),
             };
         }
         const parent = dirname(current);

package/dist/host/digests.js

@@ -23,7 +23,15 @@ export function digestProjectBundle(project) {
     try {
         const packageDir = join(staging, "package");
         mkdirSync(packageDir, { recursive: true });
-        cpSync(project.composePath, join(packageDir, "compose.yaml"));
+        // Runtime members are whichever of the two exist; validate already refuses
+        // a project that has both or neither. The Broker computes the same set
+        // (packages/broker/src/digest.ts), so the two digests have to agree.
+        if (existsSync(project.composePath)) {
+            cpSync(project.composePath, join(packageDir, "compose.yaml"));
+        }
+        if (project.nativePath && existsSync(project.nativePath)) {
+            cpSync(project.nativePath, join(packageDir, "native.yaml"));
+        }
         cpSync(project.contractPath, join(packageDir, "synology-app.yaml"));
         const htmlDir = join(project.root, "html");
         if (existsSync(htmlDir)) {

package/dist/host/dsm-client.d.ts

@@ -4,3 +4,10 @@ export interface CreateNasHostOptions {
     credentials?: HostCredentials;
 }
 export declare function createNasHost(options?: CreateNasHostOptions): NasHost | null;
+/**
+ * DSM reports the CPU vendor, not the ISA. Every x86_64 platform Synology
+ * ships is Intel or AMD; every aarch64 one is Realtek, Marvell, Annapurna or
+ * Rockchip. An unrecognised vendor returns undefined so `deploy` asks for
+ * `--arch` rather than guessing wrong and building an unusable SPK.
+ */
+export declare function archFamilyForCpuVendor(vendor: string | undefined): "x86_64" | "aarch64" | undefined;

package/dist/host/dsm-client.js

@@ -172,6 +172,15 @@ function createDsmNasHost(credentials, profileName) {
                 projectEnvCache.delete(input.packageId);
             }
         },
+        async getArchFamily() {
+            await ensureLogin();
+            const response = await dsmFetch(`${dsmOrigin}/webapi/entry.cgi?api=SYNO.Core.System&version=1&method=info`, { headers: { cookie: cookieHeader ?? "" } });
+            const body = (await response.json());
+            if (body.success !== true) {
+                return undefined;
+            }
+            return archFamilyForCpuVendor(body.data?.cpu_vendor);
+        },
         async resolveSharePath(logicalName) {
             return lookupSharePathWithSynoagentcli(logicalName, profileName);
         },
@@ -288,3 +297,19 @@ function createDsmNasHost(credentials, profileName) {
         },
     };
 }
+/**
+ * DSM reports the CPU vendor, not the ISA. Every x86_64 platform Synology
+ * ships is Intel or AMD; every aarch64 one is Realtek, Marvell, Annapurna or
+ * Rockchip. An unrecognised vendor returns undefined so `deploy` asks for
+ * `--arch` rather than guessing wrong and building an unusable SPK.
+ */
+export function archFamilyForCpuVendor(vendor) {
+    const normalized = (vendor ?? "").trim().toLowerCase();
+    if (normalized === "intel" || normalized === "amd") {
+        return "x86_64";
+    }
+    if (["realtek", "marvell", "annapurna labs", "annapurna", "rockchip"].includes(normalized)) {
+        return "aarch64";
+    }
+    return undefined;
+}

package/dist/host/types.d.ts

@@ -43,6 +43,12 @@ export interface NasHost {
         spkPath: string;
         extraValues?: Record<string, string>;
     }): Promise<void>;
+    /**
+     * CPU family of this NAS, for picking a native App's target. Returns
+     * undefined when the DSM answer does not map to a family we ship, so the
+     * caller refuses instead of guessing.
+     */
+    getArchFamily?(): Promise<"x86_64" | "aarch64" | undefined>;
     resolveSharePath?(logicalName: string): Promise<string | undefined>;
     getInstalledProjectEnv?(packageIdentity: string): Promise<Record<string, string> | undefined>;
     ensurePackageSource?(origin: string): Promise<void>;

package/dist/init.js

@@ -6,6 +6,7 @@ const TEMPLATE_NAMES = [
     "hello-web-page",
     "hello-files",
     "compose-import",
+    "native",
 ];
 export function isTemplateName(value) {
     return TEMPLATE_NAMES.includes(value);

package/dist/native/load.d.ts

@@ -0,0 +1,8 @@
+import { type Document } from "yaml";
+import type { NativeConfig } from "./types.js";
+export interface ParsedNative {
+    native: NativeConfig;
+    source: string;
+    doc: Document;
+}
+export declare function loadNative(nativePath: string): ParsedNative | null;

package/dist/native/load.js

@@ -0,0 +1,11 @@
+import { existsSync, readFileSync } from "node:fs";
+import { parseDocument } from "yaml";
+export function loadNative(nativePath) {
+    if (!existsSync(nativePath)) {
+        return null;
+    }
+    const source = readFileSync(nativePath, "utf8");
+    const doc = parseDocument(source);
+    const native = (doc.toJSON() ?? {});
+    return { native, source, doc };
+}

package/dist/native/types.d.ts

@@ -0,0 +1,28 @@
+import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
+/** One target's binary source. `path` is Personal-only; Curated needs `url` + `sha256`. */
+export interface NativeTarget {
+    path?: string;
+    url?: string;
+    sha256?: string;
+    strip_components?: number;
+}
+/**
+ * The single service process a native App runs. `exec` is relative to
+ * SYNOPKG_PKGDEST, which N0 proved is the payload root itself. There is no
+ * `user:` field: DSM creates the package user at install time and already owns
+ * SYNOPKG_PKGVAR, so generated scripts neither create a user nor chown.
+ */
+export interface NativeService {
+    exec: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+/** Parsed `native.yaml`. Schema 1 only; unknown or higher versions are refused. */
+export interface NativeConfig {
+    schema: number;
+    targets: Partial<Record<NativeArchFamily, NativeTarget>>;
+    service: NativeService;
+}
+export declare const NATIVE_FILENAME = "native.yaml";
+/** Data written into SYNOPKG_PKGVAR survives upgrades; `target/` is replaced wholesale. */
+export declare const PKGVAR_PLACEHOLDER = "${SYNOPKG_PKGVAR}";

package/dist/native/types.js

@@ -0,0 +1,3 @@
+export const NATIVE_FILENAME = "native.yaml";
+/** Data written into SYNOPKG_PKGVAR survives upgrades; `target/` is replaced wholesale. */
+export const PKGVAR_PLACEHOLDER = "${SYNOPKG_PKGVAR}";

package/dist/native/validate.d.ts

@@ -0,0 +1,6 @@
+import type { ValidationError } from "../types.js";
+import type { ParsedNative } from "./load.js";
+export interface NativeValidationOptions {
+    profile?: "personal" | "listing";
+}
+export declare function validateNative(parsed: ParsedNative, nativeFile: string, options?: NativeValidationOptions): ValidationError[];

package/dist/native/validate.js

@@ -0,0 +1,144 @@
+import { makeError } from "../errors.js";
+import { isNativeArchFamily } from "../build-spk/dsm-arch.js";
+import { PKGVAR_PLACEHOLDER } from "./types.js";
+import { getValuePosition } from "../contract/load.js";
+function nativeSpan(file, doc, pathSegments, pathString) {
+    const dotPath = pathString ?? pathSegments.join(".");
+    if (!doc) {
+        return { file, line: 1, column: 1, path: dotPath };
+    }
+    const pos = getValuePosition(doc, pathSegments) ?? { line: 1, column: 1 };
+    return { file, line: pos.line, column: pos.column, path: dotPath };
+}
+const HEX64_REGEX = /^[0-9a-fA-F]{64}$/;
+const FORBIDDEN_SERVICE_FIELDS = ["user", "command", "pre_start", "post_start", "shell"];
+export function validateNative(parsed, nativeFile, options = {}) {
+    const errors = [];
+    const profile = options.profile ?? "personal";
+    const { native, doc } = parsed;
+    const rawObj = (native && typeof native === "object" ? native : {});
+    // 1. schema 必須是整數且只接受 1。未知或更高值 → 拒絕，不靜默降級。
+    if (typeof native.schema !== "number" || !Number.isInteger(native.schema) || native.schema !== 1) {
+        errors.push(makeError("NATIVE_SCHEMA_INVALID", nativeSpan(nativeFile, doc, ["schema"]), `native.yaml schema 必須是整數且只接受 1，收到 ${JSON.stringify(native.schema)}。`, "請將 schema 設定為 1。"));
+    }
+    // 3. targets 的 key 只接受 x86_64、aarch64，至少要有一個。其他 key → 拒絕。
+    const targets = rawObj.targets;
+    if (!targets || typeof targets !== "object" || Array.isArray(targets)) {
+        errors.push(makeError("NATIVE_TARGETS_REQUIRED", nativeSpan(nativeFile, doc, ["targets"]), "native.yaml 必須包含 targets 物件，且至少宣告一個架構（x86_64 或 aarch64）。", "請在 targets 底下宣告 x86_64 或 aarch64 的 binary 來源。"));
+    }
+    else {
+        const targetEntries = Object.entries(targets);
+        if (targetEntries.length === 0) {
+            errors.push(makeError("NATIVE_TARGETS_EMPTY", nativeSpan(nativeFile, doc, ["targets"]), "targets 不得為空，至少要宣告一個架構（x86_64 或 aarch64）。", "請在 targets 底下宣告 x86_64 或 aarch64 的 binary 來源。"));
+        }
+        for (const [archKey, targetVal] of targetEntries) {
+            if (!isNativeArchFamily(archKey)) {
+                errors.push(makeError("NATIVE_ARCH_UNKNOWN", nativeSpan(nativeFile, doc, ["targets", archKey]), `不支援的架構「${archKey}」，targets 的 key 只接受 x86_64 或 aarch64。`, "請將 targets 的 key 改為 x86_64 或 aarch64。"));
+                continue;
+            }
+            if (!targetVal || typeof targetVal !== "object" || Array.isArray(targetVal)) {
+                errors.push(makeError("NATIVE_TARGET_INVALID", nativeSpan(nativeFile, doc, ["targets", archKey]), `targets.${archKey} 必須是物件。`, "請指定 path 或 url 及 sha256。"));
+                continue;
+            }
+            const targetObj = targetVal;
+            const hasPath = typeof targetObj.path === "string" && targetObj.path.trim().length > 0;
+            const hasUrl = typeof targetObj.url === "string" && targetObj.url.trim().length > 0;
+            // 4. 每個 target 必須恰好有 path: 或 url: 之一。
+            if ((hasPath && hasUrl) || (!hasPath && !hasUrl)) {
+                errors.push(makeError("NATIVE_TARGET_SOURCE_EXCLUSIVE", nativeSpan(nativeFile, doc, ["targets", archKey]), `targets.${archKey} 必須恰好有 path 或 url 之一。`, "請只提供 path（本機開發）或 url（發佈）。"));
+            }
+            // 5. path: 只在 personal profile 合法。listing profile 只接受 url: ＋ sha256:（url 沒有 sha256 也要拒絕）。
+            if (profile === "listing") {
+                if (hasPath) {
+                    errors.push(makeError("NATIVE_PATH_FORBIDDEN_IN_LISTING", nativeSpan(nativeFile, doc, ["targets", archKey, "path"]), `Listing profile 不允許使用 path（targets.${archKey}.path），只接受 url ＋ sha256。`, "請在 targets 中改用 url 與 sha256 指向上游 release asset。"));
+                }
+                if (hasUrl && (!targetObj.sha256 || typeof targetObj.sha256 !== "string" || targetObj.sha256.trim() === "")) {
+                    errors.push(makeError("NATIVE_SHA256_REQUIRED_IN_LISTING", nativeSpan(nativeFile, doc, ["targets", archKey]), `Listing profile 的 targets.${archKey} 必須包含 sha256。`, "請提供 64 位元 SHA-256 雜湊值。"));
+                }
+            }
+            // 6. sha256 給了就必須是 64 個 hex 字元（大小寫都收，比對時 normalize 成小寫）。
+            if (targetObj.sha256 !== undefined) {
+                if (typeof targetObj.sha256 !== "string" || !HEX64_REGEX.test(targetObj.sha256)) {
+                    errors.push(makeError("NATIVE_SHA256_INVALID", nativeSpan(nativeFile, doc, ["targets", archKey, "sha256"]), `targets.${archKey}.sha256 必須是 64 個十六進位字元 (hex)。`, "請提供有效的 64 位元 SHA-256 hex 字串。"));
+                }
+            }
+            // 7. strip_components 給了必須是 >= 0 的整數。
+            if (targetObj.strip_components !== undefined) {
+                if (typeof targetObj.strip_components !== "number" ||
+                    !Number.isInteger(targetObj.strip_components) ||
+                    targetObj.strip_components < 0) {
+                    errors.push(makeError("NATIVE_STRIP_COMPONENTS_INVALID", nativeSpan(nativeFile, doc, ["targets", archKey, "strip_components"]), `targets.${archKey}.strip_components 必須是 >= 0 的整數。`, "請提供大於或等於 0 的整數值。"));
+                }
+            }
+        }
+    }
+    // service 檢查
+    const service = rawObj.service;
+    if (!service || typeof service !== "object" || Array.isArray(service)) {
+        errors.push(makeError("NATIVE_SERVICE_REQUIRED", nativeSpan(nativeFile, doc, ["service"]), "native.yaml 必須包含 service 定義。", "請在 native.yaml 新增 service 區塊，包含 exec、args 與 env。"));
+        return errors;
+    }
+    const serviceObj = service;
+    // 10 & 11. service 禁止的欄位：user (規則10) 以及 shell 字串欄位 command, pre_start, post_start, shell 等 (規則11)
+    if ("user" in serviceObj) {
+        errors.push(makeError("NATIVE_SERVICE_USER_FORBIDDEN", nativeSpan(nativeFile, doc, ["service", "user"]), "service 不允許包含 user 欄位（DSM 在安裝時會自動建立並管理 package user）。", "請移除 service.user 欄位。"));
+    }
+    for (const forbiddenField of ["command", "pre_start", "post_start", "shell"]) {
+        if (forbiddenField in serviceObj) {
+            errors.push(makeError("NATIVE_SERVICE_SHELL_FIELD_FORBIDDEN", nativeSpan(nativeFile, doc, ["service", forbiddenField]), `service 不允許包含 shell 欄位「${forbiddenField}」，執行設定請使用 exec 與 args。`, `請移除 service.${forbiddenField}，改用 exec 與 args。`));
+        }
+    }
+    // 9. service.exec 必填、必須是相對路徑：不接受絕對路徑、不接受任何 .. path segment、不接受空字串。
+    const exec = serviceObj.exec;
+    if (typeof exec !== "string" || exec.trim() === "") {
+        errors.push(makeError("NATIVE_EXEC_REQUIRED", nativeSpan(nativeFile, doc, ["service", "exec"]), "service.exec 為必填項目，且不可為空字串。", "請提供相對於 package 根目錄的可執行檔路徑（例如 Radarr 或 bin/my-app）。"));
+    }
+    else {
+        const trimmedExec = exec.trim();
+        const segments = trimmedExec.split(/[/\\]/);
+        if (trimmedExec.startsWith("/") || trimmedExec.startsWith("\\") || segments.some((s) => s === "..")) {
+            errors.push(makeError("NATIVE_EXEC_INVALID_PATH", nativeSpan(nativeFile, doc, ["service", "exec"]), `service.exec「${exec}」必須是相對路徑，不可為絕對路徑或包含「..」路徑區段。`, "請使用純相對路徑（例如 Radarr 或 bin/app），不得以 / 開頭或包含 ..。"));
+        }
+    }
+    // 11. args 必須是字串 array
+    let argsValid = true;
+    if (serviceObj.args !== undefined) {
+        if (!Array.isArray(serviceObj.args) || !serviceObj.args.every((item) => typeof item === "string")) {
+            argsValid = false;
+            errors.push(makeError("NATIVE_ARGS_INVALID", nativeSpan(nativeFile, doc, ["service", "args"]), "service.args 必須是字串陣列（string[]）。", "請將 args 定義為字串清單，例如 [\"--config\", \"${SYNOPKG_PKGVAR}/config.yaml\"]。"));
+        }
+    }
+    // 12. env 必須是 string→string 的 map。
+    let envValid = true;
+    if (serviceObj.env !== undefined) {
+        if (!serviceObj.env ||
+            typeof serviceObj.env !== "object" ||
+            Array.isArray(serviceObj.env) ||
+            !Object.values(serviceObj.env).every((val) => typeof val === "string")) {
+            envValid = false;
+            errors.push(makeError("NATIVE_ENV_INVALID", nativeSpan(nativeFile, doc, ["service", "env"]), "service.env 必須是 string 到 string 的 key-value map。", "請確認 service.env 中每個環境變數的值皆為字串。"));
+        }
+    }
+    // 8. service.args 或 service.env 至少要出現一次 ${SYNOPKG_PKGVAR}，否則拒絕。用 PKGVAR_PLACEHOLDER 常數比對。
+    let hasPkgvarPlaceholder = false;
+    if (argsValid && Array.isArray(serviceObj.args)) {
+        for (const arg of serviceObj.args) {
+            if (typeof arg === "string" && arg.includes(PKGVAR_PLACEHOLDER)) {
+                hasPkgvarPlaceholder = true;
+                break;
+            }
+        }
+    }
+    if (!hasPkgvarPlaceholder && envValid && serviceObj.env && typeof serviceObj.env === "object" && !Array.isArray(serviceObj.env)) {
+        for (const val of Object.values(serviceObj.env)) {
+            if (typeof val === "string" && val.includes(PKGVAR_PLACEHOLDER)) {
+                hasPkgvarPlaceholder = true;
+                break;
+            }
+        }
+    }
+    if (!hasPkgvarPlaceholder) {
+        errors.push(makeError("NATIVE_PKGVAR_REQUIRED", nativeSpan(nativeFile, doc, ["service"]), `service.args 或 service.env 必須至少包含一次「${PKGVAR_PLACEHOLDER}」，以確保資料寫入持久化目錄。`, `請在 service.args 或 service.env 中傳入 ${PKGVAR_PLACEHOLDER}（例如 -data=\${SYNOPKG_PKGVAR} 或 TMPDIR: \${SYNOPKG_PKGVAR}/tmp）。`));
+    }
+    return errors;
+}