@synopackageland/cli 0.7.3 → 0.9.0

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,9 @@ 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 });
+    result.warnings?.forEach((warning) => console.error(warning));
     return result.outputs.map((output) => {
         if (!options.output)
             return output;
@@ -103,35 +127,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 +238,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
@@ -261,8 +307,9 @@ export async function runCli(argv) {
                 },
         });
         stdout(`已建立 ${options.template} 專案於 ${targetDir}`);
+        // --install-links packs a local SDK like the released package; a symlink would load the checkout's own node_modules.
         if (options.template === "native-go")
-            stdout(`下一步：\n  cd ${dir}\n  (cd backend && go test ./...)\n${existsSync(join(targetDir, "frontend", "package.json")) ? "  (cd frontend && npm ci)\n" : ""}  synopkgland build\n說明見 README.md。`);
+            stdout(`下一步：\n  cd ${dir}\n  (cd backend && go test ./...)\n${existsSync(join(targetDir, "frontend", "package.json")) ? `  (cd frontend && npm install${process.env.SYNOPKGLAND_SDK_DIR ? " --install-links" : ""})\n` : ""}  synopkgland build\n說明見 README.md。`);
     });
     program
         .command("add <caps...>")
@@ -415,9 +462,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 +486,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/error-registry.js

@@ -102,7 +102,7 @@ export const ERROR_REGISTRY = {
     "GATEWAY_BUILD_FAILED": {
         "code": "GATEWAY_BUILD_FAILED",
         "description": "DSM 驗證閘道建置失敗或產出不是對應架構的靜態 ELF。",
-        "suggestion": "請查看 go build 輸出；閘道固定以 go1.26.9 建置，離線時請安裝 go1.26.9 或讓 GOPROXY 可提供 golang.org/toolchain，並確認 templates/_gateway 未被修改。"
+        "suggestion": "請查看 go build 輸出；閘道固定以 go1.26.9 建置，離線時請安裝 go1.26.9 或讓 GOPROXY 可提供 golang.org/toolchain，並確認 CLI 套件的 assets/go/gateway 未被修改。"
     },
     "CONTRACT_INVALID_STRING": {
         "code": "CONTRACT_INVALID_STRING",
@@ -587,7 +587,7 @@ export const ERROR_REGISTRY = {
     "STANDALONE_GO_BUILD_FAILED": {
         "code": "STANDALONE_GO_BUILD_FAILED",
         "description": "go build 失敗。",
-        "suggestion": "請在 backend 目錄執行 go build ./... 並修正錯誤。"
+        "suggestion": "請在 backend 目錄執行 go build ./... 並修正錯誤。取不到 github.com/synopackageland/syno-pkg-land-sdk 時，設定 GOPRIVATE=github.com/synopackageland/* 並讓 git 能以憑證讀 github.com。"
     },
     "STANDALONE_PORTAL_INVALID": {
         "code": "STANDALONE_PORTAL_INVALID",
@@ -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。" };
@@ -690,7 +695,15 @@ export function getErrorCode(code) {
     return ERROR_REGISTRY[code];
 }
 for (const [code, description, suggestion] of [
-    ["EXECUTOR_BUILD_FAILED", "executor 或 lifecycle helper 編譯失敗，或 CLI 套件缺少 executor 原始碼。", "確認已安裝 Go 1.21 以上且可取得 go1.26.9（離線時請先備妥），查看訊息中的編譯器輸出；原始碼缺少時重新安裝 CLI。"],
+    ["EXECUTOR_BUILD_FAILED", "從 App 相依的 SDK 版本編譯 executor 或 lifecycle helper 失敗。", "確認已安裝 Go 1.21 以上且可取得 go1.26.9（離線時請先備妥），查看訊息中的編譯器輸出。"],
+    ["EXECUTOR_DIGEST_MISMATCH", "由 SDK 版本建出的 executor 與 CLI 內建的 sha256 表不符，或表中沒有這個 SDK 版本。", "確認 backend/go.mod 的 github.com/synopackageland/syno-pkg-land-sdk 是正式版本且 Go 為 go1.26.9；表中沒有該版本時升級 CLI。"],
+    ["EXECUTOR_DIGEST_UNVERIFIED", "SYNOPKGLAND_SDK_DIR 指向本機 SDK，executor 未對照 sha256 表（警告）。", "只用於開發；要發佈的 SPK 請取消 SYNOPKGLAND_SDK_DIR 後重新 build。"],
+    ["SDK_REQUIRED", "rootOps 或 delegate 需要 SDK，但 backend/go.mod 沒有 require github.com/synopackageland/syno-pkg-land-sdk。", "在 backend/go.mod 加入 require github.com/synopackageland/syno-pkg-land-sdk 與 CLI 同一 minor 的版本，或改用 init 產生的 Go 後端。"],
+    ["SDK_VERSION_MISMATCH", "frontend/package.json 的 @synopackageland/sdk 與 backend/go.mod 要求的 SDK 版本不同。", "把兩邊改成同一個版本；file: 相依時，比對的是該目錄 package.json 的 version。"],
+    ["SDK_UNSUPPORTED", "backend/go.mod 要求的 SDK 不是這個 CLI 的 minor 版本線。", "改用與 SDK 同一 minor 的 CLI，或把 SDK 升到 CLI 支援的版本線（訊息列出）。"],
+    ["SDK_DIR_NOT_READY", "SYNOPKGLAND_SDK_DIR 指向的 SDK checkout 根目錄缺少 go.mod，或 Vue 專案需要的 ts 套件尚未建置（沒有 ts/dist）。", "指向 syno-pkg-land-sdk checkout；Vue 專案先在 $SYNOPKGLAND_SDK_DIR/ts 執行 npm ci && npm run build（npm 安裝 file: 套件時不會替它 build）。"],
+    ["SDK_DOWNLOAD_FAILED", "go mod download 取不到 backend/go.mod 要求的 SDK 版本。", "SDK repo 目前是 private，不能經 proxy.golang.org 取得：設定 GOPRIVATE=github.com/synopackageland/*（例如 go env -w），並讓 git 能以憑證讀 github.com（git ls-remote 可驗證）；再確認版本存在。離線時先在同一台機器 go mod download 一次。"],
+    ["TEMPLATES_MISSING", "找不到 @synopackageland/templates。", "重新安裝 @synopackageland/cli，或把 SYNOPKGLAND_TEMPLATES_DIR 指向 templates checkout。"],
     ["EXECUTOR_PIN_REQUIRED", "宣告 rootOps 或 delegate 的套件建置時沒有 executor 產物。", "使用 synopkgland build，讓 CLI 編譯並 pin executor；不要直接呼叫低階 SPK API。"],
     ["EXECUTOR_POLICY", "capabilities.delegate 的 operations 或 scope 不合法，無法產生 executor policy。", "改用 init／add 產生的 delegate 宣告，或依 manifest 參考修正 scope 與 operations。"],
     ["EXECUTOR_PACKAGE", "pin 進 root task 的套件名稱不合法。", "package 必須以英文字母開頭，只含英數字（2–64 字）。"],
@@ -701,7 +714,7 @@ for (const [code, description, suggestion] of [
     ERROR_REGISTRY[code] = { code, description, suggestion };
 ERROR_REGISTRY["STANDALONE_ENTRY_INVALID"] = { "code": "STANDALONE_ENTRY_INVALID", "description": "entry 設定不合法。", "suggestion": "entry 填 admin-only 或 app-privilege；app-privilege 需要至少一個 authenticated route。" };
 ERROR_REGISTRY["STANDALONE_ENTRY_WIDENED"] = { "code": "STANDALONE_ENTRY_WIDENED", "description": "entry: admin-only 與放寬權限的 route 設定衝突。", "suggestion": "把 permissions.json 中 authenticated 或 public 的 route 改為 administrators；要開放給一般使用者請改用 entry: app-privilege 或省略 entry。" };
-ERROR_REGISTRY["STANDALONE_ENTRY_UNSUPPORTED"] = { "code": "STANDALONE_ENTRY_UNSUPPORTED", "description": "backend 無法強制 entry 模式。", "suggestion": "使用 Go backend，複製 SDK 的 internal/dsm entry gate 並在 cmd/app/main.go 呼叫 dsm.NewEntryGate。" };
+ERROR_REGISTRY["STANDALONE_ENTRY_UNSUPPORTED"] = { "code": "STANDALONE_ENTRY_UNSUPPORTED", "description": "backend 無法強制 entry 模式。", "suggestion": "使用 Go backend：backend/go.mod require github.com/synopackageland/syno-pkg-land-sdk，並在 cmd/app/main.go 以 dsm.NewEntryGate 包住 authenticator。" };
 ERROR_REGISTRY["DSM_TLS_UNTRUSTED"] = { "code": "DSM_TLS_UNTRUSTED", "description": "DSM 的 TLS 憑證不受這台電腦信任（自簽、過期或名稱不符）。", "suggestion": "把 NAS 憑證或其 CA 匯出成 PEM，用 NODE_EXTRA_CA_CERTS=<該檔> 執行；或讓 DSM 使用與 host profile 名稱相符的受信任憑證。不要關閉憑證驗證。" };
 ERROR_REGISTRY["STANDALONE_ICON_INVALID"] = { "code": "STANDALONE_ICON_INVALID", "description": "dsm-package.yaml 的 icon 不是可用的套件圖示。", "suggestion": "icon 填專案內的正方形 PNG（至少 256×256），或含 icon_256.png 的 icon_<size>.png 目錄；省略則使用 SDK 預設圖示。" };
 ERROR_REGISTRY["CONTRACT_ICON_INVALID"] = { "code": "CONTRACT_ICON_INVALID", "description": "synology-app.yaml 的 icon 不是可用的套件圖示。", "suggestion": "icon 填專案內的正方形 PNG（至少 256×256），或含 icon_256.png 的 icon_<size>.png 目錄；省略則使用 SDK 預設圖示。" };

package/dist/info.js

@@ -8,6 +8,7 @@ import { inspectSpk } from "./standalone/inspect-spk.js";
 import { isNativeLayout, loadNativeLayout } from "./standalone/native-layout.js";
 import { executorPolicy, executorPolicyText, sha256 } from "./runtime/executor-policy.js";
 import { executorTasks } from "./runtime/executor-tasks.js";
+import { requiredSdk } from "./runtime/sdk-source.js";
 import { uninstallCleanup } from "./runtime/uninstall-cleanup.js";
 export async function projectInfo(options) {
     const identity = resolveDeployIdentity(options.project, { dev: options.dev });
@@ -68,7 +69,7 @@ export function classifyRootTasks(expected, inventory) {
 async function liveRootCapability(m, host) {
     try {
         const policyDigest = sha256(executorPolicyText(executorPolicy(m)));
-        const classified = classifyRootTasks(executorTasks({ package: m.package, policyDigest }), await host.getRootTaskInventory?.(m.package));
+        const classified = classifyRootTasks(executorTasks({ package: m.package, policyDigest }, requiredSdk(m.backend.kind === "go" ? m.backend.dir : m.root).executorDir), await host.getRootTaskInventory?.(m.package));
         if (classified.state !== "ready")
             return classified;
         const observed = await host.getExecutorStatus?.(m.package);

package/dist/init.js

@@ -3,8 +3,10 @@ import { isMap, isScalar, parse, parseDocument, stringify } from "yaml";
 import { capabilityNames, capabilitySettings } from "./capabilities.js";
 import { MOVE_FROM_STAGING } from './runtime/delegate-contract.js';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { basename, join, relative } from "node:path";
+import { basename, join, relative, resolve } from "node:path";
+import { SDK_MODULE, SDK_PACKAGE } from "./runtime/sdk-source.js";
 import { templatesRoot } from "./template-paths.js";
+import { borrowedTarget, capabilityOverlays } from "./capability-overlays.js";
 import { resolveMinDsm, assertContainerMinDsm, DEFAULT_MIN_DSM, isDsmAtLeast } from "./build-spk/dsm-version.js";
 import { readSharedFolder } from "./standalone/shared-folder.js";
 const TEMPLATE_NAMES = [
@@ -35,20 +37,8 @@ export function nativeCapabilitySettings(names) {
         };
     return settings;
 }
-/**
- * native-go --with root-ops: files laid over the native-go template, and the
- * files they replace.
- */
-const ROOT_OVERLAY = "native-go-root-ops";
-const ROOT_REPLACED = ["backend/internal/app/root_none.go"];
-/** native-go --with jobs: overlay with the routes, the UI panel and the docs. */
-const BACKGROUND_OVERLAY = "native-go-jobs";
-const BACKGROUND_REPLACED = ["backend/internal/app/background_none.go"];
-/** Templates whose identity is filled in at init (placeholders in these files). */
-const SUBSTITUTED = {
-    "native-go": ["dsm-package.yaml", "README.md"],
-    "binary": ["dsm-package.yaml", "ui/app.js"],
-};
+/** Templates whose identity is filled in at init: every generated file may carry a placeholder. */
+const IDENTIFIED = ["native-go", "binary"];
 const PACKAGE_ID = /^[A-Za-z][A-Za-z0-9]{1,63}$/;
 /** npm never publishes files named .gitignore, so templates ship them as `gitignore`. */
 const RENAMED = { gitignore: ".gitignore" };
@@ -105,8 +95,9 @@ export function initFromTemplate(template, targetDir, options = {}) {
         throw new Error("[INIT_OPTIONS_UNSUPPORTED] --from 只適用於 compose。");
     if (caps.length && template !== "native-go")
         throw new Error("[CAPABILITY_UNSUPPORTED] binary／compose 不支援 --with 能力。");
-    const background = caps.includes("jobs") || caps.includes("delegate");
-    const executor = caps.includes("root-ops") || caps.includes("delegate");
+    const localSdk = template === "native-go" && process.env.SYNOPKGLAND_SDK_DIR ? resolve(process.env.SYNOPKGLAND_SDK_DIR) : undefined;
+    if (localSdk)
+        assertLocalSdkReady(localSdk, resolvedUi(template, options) === "vue");
     const source = join(templatesRoot(), template);
     if (!existsSync(source)) {
         throw new Error(`找不到模板：${template}`);
@@ -121,14 +112,8 @@ export function initFromTemplate(template, targetDir, options = {}) {
     if (rootExample && minDsm !== undefined && !isDsmAtLeast(minDsm, DEFAULT_MIN_DSM)) {
         throw new Error(`[MIN_DSM_INVALID] root templates require DSM ${DEFAULT_MIN_DSM} or later.`);
     }
-    const overlays = [
-        ...(rootExample ? [ROOT_OVERLAY] : []),
-        ...(ui === "vue" ? ["native-go-vue"] : []),
-        ...(background ? [BACKGROUND_OVERLAY] : []),
-        ...(caps.includes("login") && existsSync(join(templatesRoot(), "native-go-identity")) ? ["native-go-identity"] : []),
-        ...(caps.includes("files") && existsSync(join(templatesRoot(), "native-go-files")) ? ["native-go-files"] : []),
-        ...(caps.includes("delegate") ? ["native-go-delegate"] : []),
-    ].map(name => join(templatesRoot(), name));
+    const capability = capabilityOverlays(caps);
+    const overlays = [...(ui === "vue" ? ["native-go-vue"] : []), ...capability.overlays].map(name => join(templatesRoot(), name));
     // Shared legal resources also live in the CLI package; only the template
     // terms are an unconditional part of a generated project.
     const shared = join(templatesRoot(), "_shared");
@@ -149,35 +134,25 @@ export function initFromTemplate(template, targetDir, options = {}) {
     for (const dir of (ui === "vue" ? ["frontend"] : [])) {
         cpSync(join(shared, "third-party-notices.mjs"), join(targetDir, dir, "third-party-notices.mjs"));
     }
-    if (rootExample)
-        ROOT_REPLACED.forEach(file => rmSync(join(targetDir, file)));
-    if (caps.includes("delegate") && !rootExample) {
-        cpSync(join(templatesRoot(), ROOT_OVERLAY, "backend/internal/app/executor.go"), join(targetDir, "backend/internal/app/executor.go"));
-        cpSync(join(templatesRoot(), ROOT_OVERLAY, "backend/internal/app/executor_test.go"), join(targetDir, "backend/internal/app/executor_test.go"));
-        ROOT_REPLACED.forEach(file => rmSync(join(targetDir, file), { force: true }));
-    }
+    for (const path of capability.borrowed)
+        cpSync(join(templatesRoot(), path), join(targetDir, borrowedTarget(path)));
+    for (const file of capability.removed)
+        rmSync(join(targetDir, file));
     if (caps.includes("delegate")) {
-        rmSync(join(targetDir, "backend/internal/app/delegate_none.go"));
         const path = join(targetDir, "backend/internal/api/permissions.json");
         const policy = JSON.parse(readFileSync(path, "utf8"));
         policy.methods["app.status"] = "authenticated";
         writeFileSync(path, JSON.stringify(policy, null, 2) + "\n");
     }
-    if (background)
-        BACKGROUND_REPLACED.forEach(file => rmSync(join(targetDir, file)));
     for (const [from, to] of Object.entries(RENAMED)) {
         if (files.includes(from)) {
             renameSync(join(targetDir, from), join(targetDir, to));
         }
     }
-    for (const file of new Set([...(SUBSTITUTED[template] ?? []), ...overlays.flatMap(root => templateFiles(root))])) {
-        const path = join(targetDir, targetName(file));
-        let text = readFileSync(path, "utf8");
-        for (const [token, value] of Object.entries(substitutions)) {
-            text = text.replaceAll(token, value);
-        }
-        writeFileSync(path, text);
-    }
+    for (const file of files.map(targetName))
+        substitute(join(targetDir, file), substitutions);
+    if (localSdk)
+        useLocalSdk(targetDir, localSdk);
     if (minDsm) {
         const manifest = join(targetDir, template !== "compose" ? "dsm-package.yaml" : "synology-app.yaml");
         writeFileSync(manifest, readFileSync(manifest, "utf8").replace(/^os_min_ver:.*$/m, `os_min_ver: "${minDsm}"`));
@@ -189,20 +164,6 @@ export function initFromTemplate(template, targetDir, options = {}) {
     }
     if (ui !== "vue")
         rmSync(join(targetDir, "frontend"), { recursive: true, force: true });
-    if (background) {
-        const routeTest = join(targetDir, "backend/internal/app/routes_test.go");
-        writeFileSync(routeTest, readFileSync(routeTest, "utf8").replace('want := ""', 'want := sampleOutcome[r.Method()]'));
-    }
-    if (executor) {
-        const path = join(targetDir, "backend/internal/app/routes_test.go");
-        writeFileSync(path, readFileSync(path, "utf8").replace('if strings.HasPrefix(r.Method(), "jobs.") {', 'if r.Method() == "root.run" { want = "session_required" }\n\t\tif strings.HasPrefix(r.Method(), "jobs.") {'));
-    }
-    if (background && ui === "vue") {
-        const app = join(targetDir, "frontend/src/App.vue");
-        writeFileSync(app, readFileSync(app, "utf8")
-            .replace("import AppShell from './shell/AppShell.vue'\n", "import AppShell from './shell/AppShell.vue'\nimport BackgroundPanel from './background/BackgroundPanel.vue'\n")
-            .replace("   <!-- BACKGROUND_PANEL -->", "   <BackgroundPanel v-if=\"app\" :key=\"app.user\" :ctx=\"ctx\" />"));
-    }
     if (template !== "compose") {
         const path = join(targetDir, "dsm-package.yaml");
         const raw = parse(readFileSync(path, "utf8"));
@@ -262,6 +223,39 @@ function sharedFolderYaml(options) {
     }
     return `\ninstall:\n  sharedFolder:\n${Object.entries(folder).map(([k, v]) => `    ${k}: ${v}\n`).join("")}`;
 }
+/**
+ * A local sdk checkout must hold the Go module, and for a Vue frontend the
+ * built ts package: npm installs a file: package as it is, without its build.
+ */
+function assertLocalSdkReady(sdkDir, vue) {
+    if (!existsSync(join(sdkDir, "go.mod"))) {
+        throw new Error(`[SDK_DIR_NOT_READY] SYNOPKGLAND_SDK_DIR=${sdkDir} 沒有 go.mod；請指向 syno-pkg-land-sdk 的 checkout。`);
+    }
+    const ts = join(sdkDir, "ts");
+    if (vue && !existsSync(join(ts, "dist"))) {
+        throw new Error(`[SDK_DIR_NOT_READY] ${ts} 尚未建置；前端安裝本機 SDK 時 npm 不會替它 build。請先執行 (cd ${ts} && npm ci && npm run build)，SDK 原始碼改動後也要重新 build。`);
+    }
+}
+/** SYNOPKGLAND_SDK_DIR: the project builds against a local sdk checkout instead of the released version. */
+function useLocalSdk(targetDir, sdkDir) {
+    const goMod = join(targetDir, "backend/go.mod");
+    writeFileSync(goMod, `${readFileSync(goMod, "utf8")}\nreplace ${SDK_MODULE} => ${sdkDir}\n`);
+    const frontend = join(targetDir, "frontend/package.json");
+    if (!existsSync(frontend))
+        return;
+    const pkg = JSON.parse(readFileSync(frontend, "utf8"));
+    pkg.dependencies[SDK_PACKAGE] = `file:${join(sdkDir, "ts")}`;
+    writeFileSync(frontend, JSON.stringify(pkg, null, 2) + "\n");
+}
+/** Fill the placeholders of one generated file; files without one, or removed by an overlay, stay untouched. */
+function substitute(path, substitutions) {
+    if (!existsSync(path))
+        return;
+    const original = readFileSync(path, "utf8");
+    const text = Object.entries(substitutions).reduce((current, [token, value]) => current.replaceAll(token, value), original);
+    if (text !== original)
+        writeFileSync(path, text);
+}
 function substitutionsFor(template, targetDir, options) {
     const ui = resolvedUi(template, options);
     const caps = capabilityNames(options.with ?? []);
@@ -274,7 +268,7 @@ function substitutionsFor(template, targetDir, options) {
     }
     if (options.ui !== undefined && !["plain", "vue"].includes(options.ui))
         throw new Error("[INIT_UI_INVALID] --ui 只接受 plain 或 vue。");
-    if (!SUBSTITUTED[template]) {
+    if (!IDENTIFIED.includes(template)) {
         if (options.from && options.displayName !== undefined)
             validDisplayName(options.displayName);
         return {};

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>;