@synopackageland/cli 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,165 @@
 # Changelog
 
+## 0.8.0 (2026-10-11)
+
+Faster builds, one SPK checker for any package, and a guide for scripts and
+interpreted languages. `validate` is merged into `inspect`.
+
+繁中摘要：toolkit 改用使用者層級共用快取；新增 `build --jobs` 多架構並行與
+`build --verify-reproducible` 可重現檢查（可用依賴指紋略過）；`inspect` 對任何
+SPK 檢查 DSM 7 格式，synopkgland 建置的 SPK 另查建置合約；native layout 的
+aarch64 INFO arch 改寫機型清單、拒絕無執行權限的 script、toolkit 可用 GNU tar
+或 bsdtar 解開；新增腳本／直譯語言打包指南。無圖示的 native layout SPK 現在會
+因 `SPK_ICON_MISSING` 無法通過 inspect。
+
+### Shared toolkit cache
+
+- Native layout toolkit archives now default to one per-user cache shared by
+  every project and worktree: `$XDG_CACHE_HOME/synopkgland` or
+  `~/.cache/synopkgland` on Linux, `~/Library/Caches/synopkgland` on macOS.
+  `SYNOPKGLAND_CACHE_DIR` still overrides it. The project's
+  `.synopkgland-cache` folder is no longer used by default; delete it or point
+  `SYNOPKGLAND_CACHE_DIR` at it. The private-folder and `sha256` checks are
+  unchanged, and concurrent builds may share the cache.
+
+### Parallel architecture builds
+
+- `synopkgland build --jobs <n>` builds up to `n` architectures at the same
+  time for native-go, binary, native layout and Compose gateway projects. The
+  default stays `1`. Output files and names are byte-identical to a sequential
+  build; with `n` above 1 each output line is prefixed with its architecture.
+- SPK files now reach the output folder only after every architecture
+  succeeds, also with `--jobs 1`. A failed architecture is named in the error,
+  for example `[aarch64]`, and no SPK from that build is written. Before, the
+  architectures built before the failure stayed in `dist/`.
+- Native layout compile hooks get `SYNOPKGLAND_WORK_DIR`, an empty scratch
+  folder per architecture. `--jobs` above 1 requires `layout.payload` to
+  contain `{arch}`. Architectures that pin the same toolkit archive download it
+  once.
+- New error code `CLI_JOBS_INVALID`.
+
+### Reproducible build check
+
+- `synopkgland build --verify-reproducible [changed|always]` keeps this
+  build's SPKs as the first round, builds once more into a temporary folder
+  with an empty `GOCACHE` after removing the manifest's `reproducible.clean`
+  paths, and fails with `BUILD_NOT_REPRODUCIBLE` listing the payload and
+  metadata files that differ. Works for every project type.
+- New optional manifest block `reproducible: {inputs, clean}` in
+  `dsm-package.yaml` (native-go, binary, native layout) and
+  `synology-app.yaml`. The SHA-256 of the `inputs` files, the CLI version and
+  native layout toolkit pins form a dependency fingerprint. A passing check
+  writes it to `reproducible-fingerprint.json`; `changed` (the default) skips
+  the second build while it is unchanged. New error code
+  `REPRODUCIBLE_INVALID`.
+
+### `inspect` checks any SPK
+
+- `synopkgland inspect <spk>` now checks any SPK against the DSM 7 package
+  format, whether `synopkgland` built it or not, without installing it: the
+  outer archive, `INFO` fields, formats and `checksum`, path and link safety in
+  `package.tgz`, `ui/config` JSON and its `"texts"` declaration, ELF files
+  against `arch` (none in `noarch`), lifecycle scripts and their execute bit,
+  `conf/privilege` and `conf/resource`, icons, `LICENSE`, wizards and
+  `syno_signature.asc`. Every finding has a stable `SPK_*` code listed in the
+  errors reference.
+- Only an SPK that `synopkgland` built (top-level `sdk-package.json` or
+  `native-layout.json`, or `synology-app.yaml` in the payload) is also checked
+  against the build contract. Other SPKs are no longer rejected by it.
+- The output has a DSM format section and, for `synopkgland` SPKs, a
+  `synopkgland` contract section. An error in either exits 1 with
+  `SPK_INSPECTION_FAILED`; warnings alone exit 0. `--json` keeps every earlier
+  field and adds `synopkgland` (boolean) and `dsm: {ok, errors, warnings}`.
+- There is no `validate` command; the DSM rules it had during 0.8.0
+  development are part of `inspect`. The project check is `check`.
+
+### Native layout fixes
+
+- `arches: [aarch64]` now writes the same `INFO` `arch` as native-go and
+  binary (`armada37xx rtd1296 rtd1619 rtd1619b`) instead of `aarch64`, which
+  the Developer Guide arch table does not list.
+- `build` refuses a lifecycle or replace script in `layout.metadata` without
+  the execute bit with `NATIVE_LAYOUT_SCRIPT_NOT_EXECUTABLE`; run `chmod +x`.
+  Before, the SPK was built and DSM could not run the script.
+- `native.toolkits` archives extract with GNU tar and with bsdtar (the macOS
+  default). Other tar programs fail with `NATIVE_TOOLKIT_TAR_UNSUPPORTED`.
+  Members with absolute or `..` paths are refused.
+
+### Scripts and interpreted languages guide
+
+- New guide: package a shell, Node.js, Python, Bun or Deno program by
+  compiling it to one executable, bundling the interpreter through
+  `native.toolkits`, or running it in a Compose container, with measured sizes,
+  architectures and glibc needs, and a hand-packed `noarch` shell SPK. The CLI
+  cannot declare `install_dep_packages` for Package Center's Node.js or Python
+  packages; the guide says so.
+
+### 繁體中文摘要
+
+- `synopkgland build --jobs <n>` 可同時建置多個架構（native-go、binary、native layout、
+  Compose gateway），預設仍為 1；產出與依序建置逐位元組相同。所有架構成功後才寫入
+  SPK，失敗時錯誤標明架構且不寫入任何 SPK。native layout hook 新增
+  `SYNOPKGLAND_WORK_DIR`；`--jobs` 大於 1 時 `layout.payload` 必須含 `{arch}`。
+- `synopkgland build --verify-reproducible` 以這次建置為第一輪、從乾淨狀態再建一次比對，
+  不同時列出 payload 檔案並以 `BUILD_NOT_REPRODUCIBLE` 失敗。manifest 新增
+  `reproducible: {inputs, clean}`；依賴指紋未變時略過（記錄在
+  `reproducible-fingerprint.json`）。
+- native layout 的 toolkit 快取預設改為每位使用者一份、所有專案與 worktree 共用
+  （Linux `$XDG_CACHE_HOME/synopkgland` 或 `~/.cache/synopkgland`，macOS
+  `~/Library/Caches/synopkgland`）；`SYNOPKGLAND_CACHE_DIR` 仍可覆寫。專案內的
+  `.synopkgland-cache` 不再預設使用。
+- `synopkgland inspect <spk>` 改為不安裝、依 DSM 7 套件格式檢查任何 SPK（不限本 CLI 建置），
+  涵蓋外層封存、`INFO` 欄位與 `checksum`、`package.tgz` 路徑與連結安全、`ui/config` 的
+  `"texts"`、ELF 與 `arch`（`noarch` 不得有 ELF）、生命週期指令碼與執行權限、`conf/privilege`
+  與 `conf/resource`、圖示、`LICENSE`、精靈與簽章。每個問題有固定 `SPK_*` 代碼，列在錯誤碼參考。
+- 只有 `synopkgland` 建置的 SPK（最上層有 `sdk-package.json` 或 `native-layout.json`，或 payload
+  有 `synology-app.yaml`）另查建置合約；其他 SPK 不再因合約被拒。任一區段有錯誤時以
+  `SPK_INSPECTION_FAILED` 結束碼 1 失敗，只有警告時結束碼 0。`--json` 保留原有欄位，新增
+  `synopkgland` 與 `dsm: {ok, errors, warnings}`。
+- 沒有 `validate` 指令；0.8.0 開發期間的 DSM 規則已併入 `inspect`。專案檢查請用 `check`。
+- native layout 以 `arches: [aarch64]` 建置時，INFO `arch` 改為與 native-go／binary 相同的
+  `armada37xx rtd1296 rtd1619 rtd1619b`。`layout.metadata` 的指令碼沒有執行權限時 `build` 以
+  `NATIVE_LAYOUT_SCRIPT_NOT_EXECUTABLE` 拒絕，請 `chmod +x`。`native.toolkits` 可用 GNU tar 與
+  bsdtar 解壓，其他 tar 以 `NATIVE_TOOLKIT_TAR_UNSUPPORTED` 失敗。
+- 新增「封裝指令碼與直譯式語言」指南：編譯成單一執行檔、經 `native.toolkits` 附帶直譯器、或以
+  Compose 容器執行，附實測大小、架構與 glibc 需求，以及手動打包的 `noarch` shell SPK。CLI 無法宣告
+  `install_dep_packages` 依賴套件中心的 Node.js／Python 套件，指南已明確說明。
+
+## 0.7.3 (2026-10-11)
+
+Rebuild every package built with 0.7.2 that has `i18n.info` translations. In
+0.7.2 its DSM main-menu entry, desktop shortcut and window title showed the raw
+key `synopkgland:app_title` in every language.
+
+### Translated DSM title fix
+
+- `ui/config` entries that use the `synopkgland:app_title` and `app_desc`
+  strings now declare `"texts": "texts"`: the main-menu `app` entry, its window
+  `lib` entry and the `.url` entry of a `synology-app.yaml` app. DSM loads
+  `ui/texts/<DSM language>/strings` only for entries that declare `texts`, so
+  0.7.2 titles never resolved (seen on DSM 7.4 and 7.1.1). Without `i18n.info`
+  `ui/config` is unchanged.
+
+### Correction to 0.7.2
+
+- 0.7.2 said `synology-app.yaml` `i18n.info` localizes the DSM window title.
+  It localizes the DSM main-menu and desktop label only. `launch: dsm-window`
+  adds a main-menu and desktop entry that DSM always opens in a new browser
+  tab, as it does for every URL entry; the app has no DSM window and no window
+  title. This is not caused by DSM's CSRF protection setting. The container app
+  guide and the `synology-app.yaml` reference now say so.
+
+### 繁體中文摘要
+
+- 修正 0.7.2 的在地化標題：有 `i18n.info` 翻譯時，`ui/config` 中使用 `synopkgland:` 字串的
+  `app`、`lib` 與 `.url` 項目都加上 `"texts": "texts"`。0.7.2 少了這個欄位，DSM 不會載入
+  `ui/texts/<語言>/strings`，主選單、桌面捷徑與視窗標題在各語言都顯示 `synopkgland:app_title`。
+- 用 0.7.2 建置且含 `i18n.info` 的套件，請以 0.7.3 重新建置並遞增 build 後重新發佈；沒有
+  `i18n.info` 的套件不受影響。
+- 更正 0.7.2：`synology-app.yaml` 的 `i18n.info` 只翻譯 DSM 主選單與桌面標籤，沒有視窗標題。
+  `launch: dsm-window` 的項目一律由 DSM 在新的瀏覽器分頁開啟（DSM 對所有網址項目都如此），
+  與 CSRF 防護設定無關；容器 App 指南與 `synology-app.yaml` 參考已更正。
+
 ## 0.7.2 (2026-10-11)
 
 Rebuild packages to pick up the new default icon. Packages without `icon` now

package/README.md

@@ -64,7 +64,7 @@ Device lifecycle acceptance on real hardware is still pending for delegate and r
 | `add` | Add capabilities or `portal` to a project |
 | `check` | Validate the manifest, capability combinations and Compose file |
 | `build` | Build the SPK for one or more architectures |
-| `inspect` | Inspect an SPK without installing it |
+| `inspect` | Check any SPK against the DSM 7 package format without installing it; SPKs built by synopkgland also get the build contract |
 | `deploy` | Build and install on a NAS |
 | `status` | Show package state, Open URL and capability readiness |
 | `logs` | Show package status diagnostics |

package/dist/build-spk/gateway.d.ts

@@ -21,11 +21,11 @@ export declare function buildGatewayBinary(input: {
     config: GatewayConfig;
     work: string;
     run?: CommandRunner;
-}): {
+}): Promise<{
     binary: string;
 } | {
     error: GatewayErrorCode;
     detail: string;
-};
+}>;
 /** Puts the CGI (mode 0755) and its readable configuration into the package payload. */
 export declare function writeGatewayPayload(packageDir: string, binary: string, config: GatewayConfig): void;

package/dist/build-spk/gateway.js

@@ -24,10 +24,10 @@ export function gatewayConfig(contract, adminport) {
     };
 }
 /** Compiles the fixed gateway module for `arch`; the result is a static ELF or a coded failure. */
-export function buildGatewayBinary(input) {
+export async function buildGatewayBinary(input) {
     const out = join(input.work, `gateway-${input.arch}.cgi`);
     const ldflags = ["-s", "-w", "-buildid=", `-X main.packageID=${input.packageId}`, `-X 'main.configJSON=${JSON.stringify(input.config)}'`].join(" ");
-    const result = (input.run ?? runCommand)("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, "."], {
+    const result = await (input.run ?? runCommand)("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, "."], {
         cwd: join(templatesRoot(), "_gateway"),
         env: { ...process.env, ...pinnedGoBuildEnv(input.arch) },
     });

package/dist/build-spk/generator.d.ts

@@ -20,6 +20,7 @@ export interface BuildSpkResult {
     errors: string[];
 }
 export declare function buildSpk(options: BuildSpkOptions): Promise<BuildSpkResult>;
+export declare function walkFiles(root: string, prefix?: string): string[];
 export declare function digestSpkPayload(spkPath: string): Promise<string>;
 export declare function extractSpk(spkPath: string, targetDir: string): Promise<void>;
 export declare function readInfoPackage(spkDir: string): string | null;

package/dist/build-spk/generator.js

@@ -99,7 +99,7 @@ export async function buildSpk(options) {
     try {
         let gatewayBinary;
         if (gateway) {
-            const built = buildGatewayBinary({
+            const built = await buildGatewayBinary({
                 packageId: String(contract.package),
                 arch: options.archFamily,
                 config: gateway,
@@ -862,7 +862,7 @@ async function createDeterministicSpk(stagingDir, outputPath) {
     }
     await createReproducibleTar(stagingDir, outputPath);
 }
-function walkFiles(root, prefix = "") {
+export function walkFiles(root, prefix = "") {
     const files = [];
     for (const entry of readdirSync(root).sort()) {
         const relative = prefix ? `${prefix}/${entry}` : entry;

package/dist/build-spk/ui-texts.d.ts

@@ -9,10 +9,13 @@ export interface AppTitle {
  * `ui/config` title fields. With translations they are `section:key`
  * references DSM resolves from `ui/texts/<lang>/strings` for the main menu
  * and the window title; without, the literal English text as before.
+ * DSM loads those strings only for entries that declare `texts`. Spread the
+ * result into an entry; absent fields stay out of the JSON.
  */
 export declare function uiTitleFields(app: AppTitle): {
     title: string;
     desc: string;
+    texts?: string;
     preloadTexts?: string[];
 };
 /** `ui/texts/<dsm lang>/strings` for English and every translated language; none without translations. */

package/dist/build-spk/ui-texts.js

@@ -4,6 +4,8 @@ import { DSM_LANGS, LOCALES } from "../standalone/i18n.js";
 const SECTION = "synopkgland";
 const TITLE = `${SECTION}:app_title`;
 const DESC = `${SECTION}:app_desc`;
+/** `ui/` subdirectory with the strings; a `ui/config` entry's `texts` names it relative to `ui/`. */
+const TEXTS_DIR = "texts";
 function translated(app) {
     return Object.values(app.info ?? {}).some((text) => text?.displayname || text?.description);
 }
@@ -11,10 +13,12 @@ function translated(app) {
  * `ui/config` title fields. With translations they are `section:key`
  * references DSM resolves from `ui/texts/<lang>/strings` for the main menu
  * and the window title; without, the literal English text as before.
+ * DSM loads those strings only for entries that declare `texts`. Spread the
+ * result into an entry; absent fields stay out of the JSON.
  */
 export function uiTitleFields(app) {
     return translated(app)
-        ? { title: TITLE, desc: DESC, preloadTexts: [TITLE, DESC] }
+        ? { title: TITLE, desc: DESC, texts: TEXTS_DIR, preloadTexts: [TITLE, DESC] }
         : { title: app.displayname, desc: app.description };
 }
 /** `ui/texts/<dsm lang>/strings` for English and every translated language; none without translations. */
@@ -34,8 +38,8 @@ export function renderUiTexts(app) {
 }
 export function writeUiTexts(uiRoot, app) {
     for (const [lang, strings] of renderUiTexts(app)) {
-        mkdirSync(join(uiRoot, "texts", lang), { recursive: true });
-        const path = join(uiRoot, "texts", lang, "strings");
+        mkdirSync(join(uiRoot, TEXTS_DIR, lang), { recursive: true });
+        const path = join(uiRoot, TEXTS_DIR, lang, "strings");
         writeFileSync(path, strings, "utf8");
         chmodSync(path, 0o644);
     }

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { Command, CommanderError } from "commander";
-import { existsSync, readFileSync, renameSync } from "node:fs";
-import { resolve, dirname, join } from "node:path";
+import { existsSync, readFileSync, renameSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { basename, resolve, dirname, join } from "node:path";
 import { findProjectRoot } from "./discovery.js";
 import { loadContract } from "./contract/load.js";
 import { contractIconPath } from "./contract/icon.js";
@@ -27,8 +28,10 @@ import { formatSkillList, readSkill, resolveSkillsRoot } from "./skill.js";
 import { resolveInstallParameterExtraValues } from "./deploy/param-values.js";
 import { findStandaloneRoot, loadStandaloneManifest, } from "./standalone/manifest.js";
 import { buildNativeLayout, isNativeLayout, loadNativeLayout, LAYOUT_ARCHES } from "./standalone/native-layout.js";
-import { buildStandalone } from "./standalone/build.js";
-import { inspectSpk } from "./standalone/inspect-spk.js";
+import { buildStandalone, runnerFor } from "./standalone/build.js";
+import { checkJobs, commitOutputs, forEachArch } from "./standalone/arch-jobs.js";
+import { checkReproducible } from "./reproducible.js";
+import { inspectAnySpk } from "./spk/inspect.js";
 function failure(code, message, hint = "修正設定後重試；使用 --help 查看指令用法。") {
     return Object.assign(new Error(`[${code}] ${message}`), { code, hint });
 }
@@ -61,13 +64,38 @@ function formatIconReport(report, manifestFile) {
         ...(report.solid ? { warning: "warning：圖示只有單一顏色，Package Center 與 DSM 主選單會像一個色塊；建議換成有圖形的圖示。" } : {}),
     };
 }
-function formatSpkInspection(spk, report) {
+const LABEL = { error: "錯誤", warning: "警告" };
+/** One line per finding: severity, stable code, where, and what to fix. */
+function formatFindings(findings) {
+    return findings.map((f) => `${LABEL[f.severity]} ${f.code}${f.path ? ` ${f.path}` : ""}: ${f.message}`);
+}
+/** The DSM format section, and the build contract section for an SPK synopkgland built. */
+function formatSpkChecks(report) {
+    const { errors, warnings } = report.dsm;
+    return [
+        "DSM 格式：",
+        ...formatFindings([...errors, ...warnings]).map((line) => `  ${line}`),
+        `  ${report.dsm.ok ? "符合" : "不符合"} DSM 7 套件格式：${errors.length} 個錯誤、${warnings.length} 個警告。`,
+        ...(report.synopkgland
+            ? [
+                "synopkgland 合約：",
+                report.findings.length
+                    ? "  問題："
+                    : report.executor
+                        ? "  檢查：沒有異常。管理員核准後會建立 root executor 排程（boot 與 control task），以 root 執行此 SPK 固定的 executor 與 policy。"
+                        : "  檢查：沒有 root 權限需求或異常。",
+                ...report.findings.map((f) => `    - ${f}`),
+            ]
+            : []),
+    ];
+}
+function formatSpkReport(spk, report) {
     return [
         `SPK：${spk}`,
         `package：${report.package ?? "?"}  version：${report.version ?? "?"}`,
-        `arch：${report.arch ?? "?"}  runtime：${report.kind ?? "?"}`,
+        report.synopkgland ? `arch：${report.arch ?? "?"}  runtime：${report.kind ?? "?"}` : `arch：${report.arch ?? "?"}  建置：不是 synopkgland（只檢查 DSM 格式）`,
         `簽署：${report.signed ? "有 Synology 簽章" : "未簽署（Package Center 需允許任何發行者）"}`,
-        `CGI：${report.cgi ?? "無"}`,
+        ...(report.synopkgland ? [`CGI：${report.cgi ?? "無"}`] : []),
         ...(report.icon ? [`圖示：${report.icon.source === "default" ? "SDK 預設圖示" : report.icon.source === "custom" ? `自訂（PACKAGE_ICON_256 sha256 ${report.icon.sha256.slice(0, 12)}…）` : "無 PACKAGE_ICON"}`] : []),
         ...(report.entry === "admin-only" ? ["入口：entry: admin-only，只有 DSM 管理員能開啟與呼叫任何 route（含 SDK routes）"] : []),
         ...(report.entry === "app-privilege" ? ["入口：entry: app-privilege，由 DSM 控制台「應用程式權限」決定誰能使用"] : []),
@@ -76,12 +104,7 @@ function formatSpkInspection(spk, report) {
         "payload：",
         ...(report.uninstallCleanup ?? []).map(item => `Uninstall cleanup (if needed)：${item.target} — ${item.condition} ${item.action}`),
         ...report.payload.map((e) => `  ${e.mode} ${e.path}`),
-        report.findings.length
-            ? "問題："
-            : report.executor
-                ? "檢查：沒有異常。管理員核准後會建立 root executor 排程（boot 與 control task），以 root 執行此 SPK 固定的 executor 與 policy。"
-                : "檢查：沒有 root 權限需求或異常。",
-        ...report.findings.map((f) => `  - ${f}`),
+        ...formatSpkChecks(report),
     ].join("\n");
 }
 async function standaloneBuild(root, arches, options) {
@@ -93,8 +116,8 @@ async function standaloneBuild(root, arches, options) {
             ? resolve(options.outDir)
             : undefined;
     const result = isNativeLayout(root)
-        ? await buildNativeLayout({ root, arches, outDir, minDsm: options.minDsm })
-        : await buildStandalone({ root, arches: arches, outDir, minDsm: options.minDsm });
+        ? await buildNativeLayout({ root, arches, outDir, minDsm: options.minDsm, jobs: options.jobs })
+        : await buildStandalone({ root, arches: arches, outDir, minDsm: options.minDsm, jobs: options.jobs });
     return result.outputs.map((output) => {
         if (!options.output)
             return output;
@@ -103,35 +126,55 @@ async function standaloneBuild(root, arches, options) {
         return target;
     });
 }
+/** What the reproducible check needs to know about the project being built. */
+function reproducibleTarget(standalone, project, arches) {
+    if (!standalone)
+        return { root: project.root, manifestPath: project.contractPath, arches: arches ?? [] };
+    const manifestPath = join(standalone, "dsm-package.yaml");
+    if (!isNativeLayout(standalone)) {
+        const loaded = loadStandaloneManifest(standalone);
+        return { root: standalone, manifestPath, arches: arches ?? (loaded.ok ? loaded.manifest.arches : []) };
+    }
+    const loaded = loadNativeLayout(standalone);
+    if (!loaded.ok)
+        return { root: standalone, manifestPath, arches: arches ?? [] };
+    // Toolkit pins decide what the native hooks compile against.
+    const toolkits = createHash("sha256").update(JSON.stringify(loaded.manifest.native.toolkits)).digest("hex");
+    return { root: standalone, manifestPath, arches: arches ?? loaded.manifest.arches, extraInputs: { "native.toolkits": toolkits } };
+}
+function reproducibleLines(report) {
+    if (report.skipped)
+        return [`可重現檢查：依賴指紋 ${report.fingerprint.slice(0, 12)} 與上次通過時相同，略過。`];
+    return report.results.map((result) => result.identical
+        ? `可重現檢查：${basename(result.output)} 相同（sha256 ${result.sha256[0].slice(0, 12)}）`
+        : `可重現檢查：${basename(result.output)} 不同（sha256 ${result.sha256[0].slice(0, 12)} ≠ ${result.sha256[1].slice(0, 12)}）\n` +
+            [...result.payload.map((file) => `  payload ${file}`), ...result.metadata.map((file) => `  metadata ${file}`)].join("\n"));
+}
 const ARCH_REQUIRED = [
     "NATIVE_ARCH_FAMILY_REQUIRED",
     "GATEWAY_ARCH_FAMILY_REQUIRED",
 ];
 async function containerBuild(project, arches, options) {
+    const jobs = checkJobs(options.jobs);
     const unsupported = arches?.find((arch) => !isContainerArchFamily(arch));
     if (unsupported)
         throw failure("CONTAINER_ARCH_UNSUPPORTED", `Container Manager App 只支援 ${CONTAINER_ARCH_FAMILIES.join("、")}；DSM 不為 ${unsupported} 提供 Container Manager。`);
     const output = options.output ? resolve(options.output) : undefined;
-    const build = (archFamily, outputPath = output) => buildSpk({ project, archFamily, outputPath, minDsm: options.minDsm });
-    let results = [];
-    if (arches?.length === 1)
-        results = [await build(arches[0])];
-    else {
-        const first = await build();
-        if (first.ok || !first.errors.every((code) => ARCH_REQUIRED.includes(code)))
-            results = [first];
-        else {
-            if (output)
-                throw failure("CLI_OUTPUT_ARCH_REQUIRED", "-o 只能搭配 --arch 建置單一架構。");
-            const packageId = String(loadContract(project.contractPath).contract.package);
-            for (const arch of arches ?? CONTAINER_ARCH_FAMILIES)
-                results.push(await build(arch, join(options.outDir ? resolve(options.outDir) : project.root, `${packageId}-${arch}.spk`)));
-        }
-    }
-    for (const result of results)
-        if (!result.ok)
+    const build = async (archFamily, outputPath = output) => {
+        const result = await buildSpk({ project, archFamily, outputPath, minDsm: options.minDsm, gatewayRun: archFamily && runnerFor(undefined, jobs, archFamily) });
+        if (!result.ok && !(archFamily === undefined && result.errors.every((code) => ARCH_REQUIRED.includes(code))))
             throw failure(result.errors[0] ?? "BUILD_FAILED", `建置失敗：${result.errors.join(", ")}`);
-    return results.map((result) => result.outputPath);
+        return result;
+    };
+    if (arches?.length === 1)
+        return [(await build(arches[0])).outputPath];
+    const first = await build();
+    if (first.ok)
+        return [first.outputPath];
+    if (output)
+        throw failure("CLI_OUTPUT_ARCH_REQUIRED", "-o 只能搭配 --arch 建置單一架構。");
+    const packageId = String(loadContract(project.contractPath).contract.package);
+    return commitOutputs(options.outDir ? resolve(options.outDir) : project.root, (stage) => forEachArch(arches ?? CONTAINER_ARCH_FAMILIES, jobs, async (arch) => (await build(arch, join(stage, `${packageId}-${arch}.spk`))).outputPath));
 }
 export async function runCli(argv) {
     const json = argv.includes("--json");
@@ -194,14 +237,16 @@ export async function runCli(argv) {
     });
     program
         .command("inspect <spk>")
-        .description("不安裝，檢查 SPK 身分、檔案與 root 權限需求")
+        .description("不安裝，依 DSM 7 套件格式檢查任何 SPK；synopkgland 建置的 SPK 另查建置合約與 root 權限需求")
         .option("--json", "輸出單一 JSON 物件")
         .action(async (input) => {
         const spk = resolve(input);
-        const report = await inspectSpk(spk);
-        if (report.findings.length)
-            throw Object.assign(failure("SPK_INSPECTION_FAILED", report.findings.join("\n"), "修正產物並重新 build；勿安裝檢查未通過的 SPK。"), { report });
-        emit("inspect", { spk, ...report }, formatSpkInspection(spk, report));
+        if (existsSync(spk) && statSync(spk).isDirectory())
+            throw failure("SPK_INSPECTION_FAILED", `${spk} 是目錄；inspect 檢查 .spk 檔。`, "檢查專案設定請用 synopkgland check。");
+        const report = await inspectAnySpk(spk);
+        if (!report.dsm.ok || report.findings.length)
+            throw Object.assign(failure("SPK_INSPECTION_FAILED", formatSpkChecks(report).join("\n"), "依錯誤碼修正 SPK 並重新打包，錯誤碼說明見 reference/errors；勿安裝檢查未通過的 SPK。"), { report: { spk, ...report } });
+        emit("inspect", { spk, ...report }, formatSpkReport(spk, report));
     });
     const images = program.command("images").description("Container image 工具");
     images
@@ -415,9 +460,14 @@ export async function runCli(argv) {
         .option("--out-dir <dir>", "輸出目錄，原生專案預設 dist/")
         .option("--arch <families>", `架構，可用逗號分隔：${NATIVE_ARCH_FAMILIES.join(",")}（armv7 用於 native-go 與 binary，不用於 Container Manager App）；native layout 另支援 armv8`)
         .option("--min-dsm <version>", "最低 DSM 版本，省略時使用 manifest 值")
+        .option("--jobs <n>", "同時建置的架構數，預設 1（依序）", Number)
+        .option("--verify-reproducible [when]", "從乾淨狀態再建置一次並比對；when：changed（預設，依賴指紋未變時略過）或 always")
         .action(async (options, command) => {
         const root = rootOf(command);
         const standalone = standaloneRoot(root);
+        const verify = options.verifyReproducible === true ? "changed" : options.verifyReproducible;
+        if (verify !== undefined && verify !== "changed" && verify !== "always")
+            throw failure("CLI_OPTION_INVALID", `--verify-reproducible 只接受 changed 或 always，收到 ${verify}。`);
         let arches;
         try {
             arches =
@@ -434,10 +484,24 @@ export async function runCli(argv) {
         catch (error) {
             throw failure("CLI_ARCH_INVALID", error instanceof Error ? error.message : String(error));
         }
-        const outputs = standalone
-            ? await standaloneBuild(standalone, arches, options)
-            : await containerBuild(requireProject(root), arches, options);
-        emit("build", { outputs }, outputs.map((output) => `已產生 ${output}`).join("\n"));
+        const project = standalone ? undefined : requireProject(root);
+        const build = (overrides = {}) => standalone
+            ? standaloneBuild(standalone, arches, { ...options, ...overrides })
+            : containerBuild(project, arches, { ...options, ...overrides });
+        const outputs = await build();
+        const reproducible = verify === undefined ? undefined : await checkReproducible({
+            ...reproducibleTarget(standalone, project, arches),
+            outputs,
+            mode: verify,
+            // The second build writes only to its own folder; a single Compose SPK keeps its name there.
+            rebuild: (outDir) => standalone || outputs.length > 1
+                ? build({ output: undefined, outDir })
+                : build({ output: join(outDir, basename(outputs[0])), outDir: undefined }),
+        });
+        const lines = [...outputs.map((output) => `已產生 ${output}`), ...(reproducible ? reproducibleLines(reproducible) : [])];
+        if (reproducible && !reproducible.identical)
+            throw Object.assign(failure("BUILD_NOT_REPRODUCIBLE", lines.join("\n"), "找出 payload 中每次建置都不同的檔案（時間戳、隨機路徑、未鎖定的依賴），修正後重試。"), { report: { outputs, reproducible } });
+        emit("build", { outputs, ...(reproducible ? { reproducible } : {}) }, lines.join("\n"));
     });
     if (json)
         console.log = (...args) => console.error(...args);

package/dist/contract/web-launch.js

@@ -141,15 +141,12 @@ export function renderWebStationResource(contract) {
 }
 export function renderDsmWindowConfig(contract) {
     const packageId = String(contract.package);
-    const { title, desc, preloadTexts } = uiTitleFields(contractAppTitle(contract));
     return `${JSON.stringify({
         ".url": {
             [packageId]: {
                 type: "url",
                 allUsers: true,
-                title,
-                desc,
-                ...(preloadTexts ? { preloadTexts } : {}),
+                ...uiTitleFields(contractAppTitle(contract)),
                 icon: "images/app_{0}.png",
                 url: trustedAppEntryPath(contract),
             },

package/dist/error-registry.js

@@ -659,11 +659,16 @@ ERROR_REGISTRY["CLI_OPTION_INVALID"] = { "code": "CLI_OPTION_INVALID", "descript
 ERROR_REGISTRY["CLI_OUTPUT_ARCH_REQUIRED"] = { "code": "CLI_OUTPUT_ARCH_REQUIRED", "description": "輸出單一檔案需要指定架構。", "suggestion": "-o 搭配單一 --arch，或使用 --out-dir。" };
 ERROR_REGISTRY["HOST_REQUIRED"] = { "code": "HOST_REQUIRED", "description": "沒有指定 NAS。", "suggestion": "使用 --host <profile>；deploy 本地檢查可用 --dry-run。" };
 ERROR_REGISTRY["NAS_CREDENTIALS_MISSING"] = { "code": "NAS_CREDENTIALS_MISSING", "description": "找不到 NAS 憑證。", "suggestion": "設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。" };
-ERROR_REGISTRY["SPK_INSPECTION_FAILED"] = { "code": "SPK_INSPECTION_FAILED", "description": "SPK 產物檢查失敗。", "suggestion": "修正 findings 並重新 build。" };
+ERROR_REGISTRY["NATIVE_LAYOUT_SCRIPT_NOT_EXECUTABLE"] = { "code": "NATIVE_LAYOUT_SCRIPT_NOT_EXECUTABLE", "description": "native layout metadata 的 scripts/ 生命週期腳本沒有執行權限（inspect 的 SPK_SCRIPT_NOT_EXECUTABLE）。", "suggestion": "在 layout metadata 目錄對該腳本執行 chmod +x 後重新 build。" };
+ERROR_REGISTRY["NATIVE_TOOLKIT_TAR_UNSUPPORTED"] = { "code": "NATIVE_TOOLKIT_TAR_UNSUPPORTED", "description": "解開 native.toolkits 需要 GNU tar 或 bsdtar，但 PATH 上的 tar 兩者都不是。", "suggestion": "讓 PATH 上的 tar 指向 GNU tar 或 bsdtar（macOS 內建 bsdtar、多數 Linux 是 GNU tar）後重新 build。" };
+ERROR_REGISTRY["SPK_INSPECTION_FAILED"] = { "code": "SPK_INSPECTION_FAILED", "description": "SPK 不符合 DSM 7 套件格式（dsm.errors），或 synopkgland 建置的 SPK 不符合建置合約（findings）。", "suggestion": "依 SPK_* 規則碼與 findings 修正後重新打包；warnings 不影響結果。" };
 ERROR_REGISTRY["IMAGE_PIN_REQUIRED"] = { "code": "IMAGE_PIN_REQUIRED", "description": "映像 digest 尚未固定。", "suggestion": "執行 images pin。" };
 ERROR_REGISTRY["INIT_TEMPLATE_REQUIRED"] = { "code": "INIT_TEMPLATE_REQUIRED", "description": "未指定模板。", "suggestion": "使用 -t native-go、binary 或 compose。" };
 ERROR_REGISTRY["INIT_TEMPLATE_UNKNOWN"] = { "code": "INIT_TEMPLATE_UNKNOWN", "description": "未知模板。", "suggestion": "使用 -t native-go、binary 或 compose。" };
 ERROR_REGISTRY["CLI_ARCH_INVALID"] = { "code": "CLI_ARCH_INVALID", "description": "架構選項不合法。", "suggestion": "使用 x86_64、aarch64 或 armv7（armv7 用於 native-go 與 binary，不用於 Container Manager App）。" };
+ERROR_REGISTRY["CLI_JOBS_INVALID"] = { "code": "CLI_JOBS_INVALID", "description": "--jobs 不是正整數。", "suggestion": "使用 --jobs 1（預設）或更大的整數。" };
+ERROR_REGISTRY["BUILD_NOT_REPRODUCIBLE"] = { "code": "BUILD_NOT_REPRODUCIBLE", "description": "build --verify-reproducible 再建置一次的 SPK 與第一次不同。", "suggestion": "查看列出的 payload 與 metadata 檔案，移除每次建置都會變的內容（時間戳、隨機或絕對路徑、未鎖定的依賴）。" };
+ERROR_REGISTRY["REPRODUCIBLE_INVALID"] = { "code": "REPRODUCIBLE_INVALID", "description": "reproducible 設定格式不對，或列出的 input 不是專案內的檔案。", "suggestion": "使用 reproducible: {inputs: [檔案...], clean: [路徑...]}，路徑相對於專案；{arch} 只能用在 clean。" };
 ERROR_REGISTRY["NATIVE_ARCH_UNDETERMINED"] = { "code": "NATIVE_ARCH_UNDETERMINED", "description": "無法判定 NAS 架構。", "suggestion": "指定 --arch x86_64、aarch64 或 armv7。" };
 ERROR_REGISTRY["DEVELOPMENT_INSTANCE_UNSUPPORTED"] = { "code": "DEVELOPMENT_INSTANCE_UNSUPPORTED", "description": "原生專案不支援 --dev。", "suggestion": "init 時指定不同 package ID。" };
 ERROR_REGISTRY["INIT_OPTIONS_UNSUPPORTED"] = { "code": "INIT_OPTIONS_UNSUPPORTED", "description": "選項不適用於這個模板。", "suggestion": "--from 僅 compose；--ui 僅 native-go。" };

package/dist/reproducible-config.d.ts

@@ -0,0 +1,8 @@
+export interface ReproducibleConfig {
+    inputs: string[];
+    clean: string[];
+}
+export declare function invalid(message: string): never;
+/** `reproducible: {inputs?: [file...], clean?: [path...]}`; `clean` paths may use `{arch}`. */
+export declare function validateReproducible(value: unknown): ReproducibleConfig;
+export declare function readReproducible(manifestPath: string): ReproducibleConfig;

package/dist/reproducible-config.js

@@ -0,0 +1,32 @@
+/** The `reproducible` manifest block, shared by dsm-package.yaml and synology-app.yaml. */
+import { readFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { parse } from "yaml";
+export function invalid(message) {
+    throw Object.assign(new Error(`[REPRODUCIBLE_INVALID] ${message}`), { code: "REPRODUCIBLE_INVALID" });
+}
+function projectPaths(value, field, arch) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > 64)
+        invalid(`reproducible.${field} must be a list of at most 64 project paths.`);
+    return value.map((path) => {
+        if (typeof path !== "string" || !path || isAbsolute(path) || /[\\\0]/.test(path) || path.split("/").some((part) => ["", ".", ".."].includes(part))
+            || (!arch && path.includes("{arch}")) || /[{}]/.test(path.replaceAll("{arch}", ""))) {
+            invalid(`reproducible.${field}: ${JSON.stringify(path)} must be a path inside the project${arch ? "" : " without {arch}"}.`);
+        }
+        return path;
+    });
+}
+/** `reproducible: {inputs?: [file...], clean?: [path...]}`; `clean` paths may use `{arch}`. */
+export function validateReproducible(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => key !== "inputs" && key !== "clean")) {
+        invalid("reproducible takes only the inputs and clean lists.");
+    }
+    const raw = value;
+    return { inputs: projectPaths(raw.inputs, "inputs", false), clean: projectPaths(raw.clean, "clean", true) };
+}
+export function readReproducible(manifestPath) {
+    const raw = parse(readFileSync(manifestPath, "utf8"));
+    return raw?.reproducible === undefined ? { inputs: [], clean: [] } : validateReproducible(raw.reproducible);
+}

package/dist/reproducible.d.ts

@@ -0,0 +1,38 @@
+import { type ReproducibleConfig } from "./reproducible-config.js";
+export { readReproducible, validateReproducible, type ReproducibleConfig } from "./reproducible-config.js";
+export interface ReproducibleResult {
+    output: string;
+    identical: boolean;
+    sha256: [string, string];
+    payload: string[];
+    metadata: string[];
+}
+export interface ReproducibleReport {
+    skipped: boolean;
+    identical: boolean;
+    fingerprint?: string;
+    changed?: string[];
+    results: ReproducibleResult[];
+}
+export declare const FINGERPRINT_RECORD = "reproducible-fingerprint.json";
+/** SHA-256 of each declared input plus the CLI version and `extra` pins, and one digest over all of them. */
+export declare function dependencyFingerprint(root: string, config: ReproducibleConfig, extra?: Record<string, string>): {
+    fingerprint: string;
+    inputs: Record<string, string>;
+};
+/**
+ * Builds the project again with `rebuild` into a temporary folder, after removing
+ * the declared `clean` paths and with an empty GOCACHE, and compares each SPK with
+ * `outputs`, the SPKs of this build. With declared inputs, mode `changed` skips
+ * while the fingerprint and architectures match the last passing record, and a
+ * passing check updates that record.
+ */
+export declare function checkReproducible(options: {
+    root: string;
+    manifestPath: string;
+    outputs: string[];
+    arches: string[];
+    mode: "changed" | "always";
+    extraInputs?: Record<string, string>;
+    rebuild: (outDir: string) => Promise<string[]>;
+}): Promise<ReproducibleReport>;