@synopackageland/cli 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,129 @@
 # Changelog
 
+## Unreleased (0.9.0)
+
+The CLI, the SDK and the project templates are now three repositories, and
+the CLI only packages, deploys and checks. An App names its SDK version once,
+in `backend/go.mod`. Background saves can create subfolders and choose what
+happens on a name conflict, and time-limited delegate jobs gain read, rename,
+copy, move and delete.
+
+繁中摘要：CLI 移到 github.com/synopackageland/syno-pkg-land-cli，只負責打包、部署與檢查；
+範本改由 `@synopackageland/templates`（精確 pin）提供；SDK 是
+`github.com/synopackageland/syno-pkg-land-sdk`（Go）與 `@synopackageland/sdk`（前端，含
+`./vue`），版本只寫在 `backend/go.mod`。`build` 依該版本 `go mod download`
+executor 並比對 CLI 內建的 sha256 表。`check` 新增 `SDK_REQUIRED`、
+`SDK_VERSION_MISMATCH`、`SDK_UNSUPPORTED`。`files.moveFromStaging` 的 `name`
+可帶子資料夾，新增 `conflict: fail|overwrite|rename`；有時限的 delegate 新增
+`files.read`、`files.rename`、`files.copy`、`files.move`、`files.delete`。
+管理員只在 executor policy 改變時需要重新核准；0.9.0 的 policy 有改變。
+
+### Repositories and the SDK version
+
+- The CLI is github.com/synopackageland/syno-pkg-land-cli, published as
+  `@synopackageland/cli`. The SDK is github.com/synopackageland/syno-pkg-land-sdk: the Go
+  module `github.com/synopackageland/syno-pkg-land-sdk` and the npm package
+  `@synopackageland/sdk`, which includes the Vue components at
+  `@synopackageland/sdk/vue`.
+- The `require github.com/synopackageland/syno-pkg-land-sdk` line in `backend/go.mod` is the
+  only SDK version. `dsm-package.yaml` has no SDK field.
+- `check` and `build` report `SDK_REQUIRED` when `capabilities.delegate` or
+  `rootOps` is declared without that line (an `entry` mode without it fails
+  with `STANDALONE_ENTRY_UNSUPPORTED`), `SDK_UNSUPPORTED` when its minor version is not the CLI's (CLI 0.9.x builds
+  SDK 0.9.x), and `SDK_VERSION_MISMATCH` when the frontend's
+  `@synopackageland/sdk` differs from it. A `file:` frontend dependency is
+  compared through that folder's `package.json` version.
+- `build` reads the SDK version from `backend/go.mod`, runs `go mod download`
+  for the executor of that version, and builds it with go1.26.9. Its sha256
+  must match the table shipped in this CLI, or the build fails with
+  `EXECUTOR_DIGEST_MISMATCH`. A version Go cannot fetch fails with
+  `SDK_DOWNLOAD_FAILED`. While the SDK repositories are private, set
+  `GOPRIVATE=github.com/synopackageland/*` and give git a credential for
+  github.com; the error says which of the two is missing. Root task scripts
+  and `sdk-permissions.json` come from the same SDK version.
+- The CGI binds both policy digests at link time:
+  `<module>/internal/api.expectedPermissionsDigest` for the App and
+  `github.com/synopackageland/syno-pkg-land-sdk/api.expectedSDKPermissionsDigest` for the
+  SDK.
+- `@synopackageland/cli/authorization-sdk` exports `AUTHORIZATION_RUNTIME`
+  and `ROOT_RUNTIME`. `authorizationTemplateDirectory` is removed;
+  `AuthorizationGate` is in `@synopackageland/sdk/vue`.
+
+### Templates
+
+- `init` and `add` read the templates from `@synopackageland/templates`, a
+  dependency pinned to an exact version. `SYNOPKGLAND_TEMPLATES_DIR` points
+  them at a templates checkout; without either, `TEMPLATES_MISSING`.
+- `init` fills the placeholders in every generated file; the Go module path
+  of a new backend is the package id. The next steps say
+  `(cd frontend && npm install)`: the templates ship no lockfile.
+- `init` and `add` share one capability overlay table (`root-ops`, `jobs`,
+  `delegate`).
+
+### Local SDK checkout
+
+- With `SYNOPKGLAND_SDK_DIR`, `init` adds
+  `replace github.com/synopackageland/syno-pkg-land-sdk => $SYNOPKGLAND_SDK_DIR` to
+  `backend/go.mod` and sets the frontend dependency to
+  `file:$SYNOPKGLAND_SDK_DIR/ts`; install it with
+  `(cd frontend && npm install --install-links)`, which packs the SDK like the
+  released package. npm does not build a `file:` package, so a Vue project
+  needs `(cd $SYNOPKGLAND_SDK_DIR/ts && npm ci && npm run build)` first, and
+  again after SDK changes; `init` refuses a checkout without `ts/dist`, or
+  without a root `go.mod`, with `SDK_DIR_NOT_READY`.
+- `build` uses `$SYNOPKGLAND_SDK_DIR/executor`, skips the digest table and
+  warns with `EXECUTOR_DIGEST_UNVERIFIED`. Do not
+  publish such an SPK; the release script refuses to run while
+  `SYNOPKGLAND_SDK_DIR` or `SYNOPKGLAND_TEMPLATES_DIR` is set.
+
+### Delegate: subfolders and conflict policy
+
+- `files.moveFromStaging` (Go: `delegate.MoveParams.Name`) accepts folders
+  below the destination, for example `Album/CD1/01.flac`. The executor's move
+  child creates missing folders as the user, after the final revoke check, so
+  a canceled move leaves none behind. Existing folders are reused. Limits: 16
+  folders, 255 bytes per name, 1024 bytes in total. A name without folders
+  behaves exactly as before.
+- New `conflict` field for `files.moveFromStaging` and the time-limited
+  `files.write`: `fail` (default, unchanged), `overwrite` (atomic replace of a
+  regular file the user can write) or `rename` (`name (1).ext` up to
+  `name (99).ext`; the receipt path reports the name used).
+- New error codes: `invalid-path`, `path-too-deep`,
+  `destination-not-directory`, `name-too-long`.
+
+### Delegate: file operations for time-limited grants
+
+- New operations `files.read`, `files.rename`, `files.copy`, `files.move` and
+  `files.delete`, each declared on its own; a write operation never implies
+  delete. Go: `job.Files()` returns `delegate.JobFiles` with `Read`, `Rename`,
+  `CreateFolderAll`, `Copy`, `Move`, `Delete`, `TaskStatus` and `CancelTask`.
+- `files.createFolder` takes `parents` (`CreateFolderAll`, like `mkdir -p`).
+- Except `files.write` and `files.read`, the executor calls File Station as the
+  user through one root-side allowlist of methods, and re-checks the paths File
+  Station reports against the grant. `files.read` copies the file into staging
+  in a child that drops to the user and never follows symlinks.
+- Copy, move and delete run as File Station background tasks followed with the
+  implied `files.taskStatus` and `files.taskCancel`; revoking the grant stops
+  them. Delete needs `recursive` for folders and goes to the recycle bin; a
+  Shared Folder without one needs `permanent`.
+- File Station refusals now report SDK codes (`PERMISSION_DENIED`,
+  `not-found`, `destination-exists`, `NO_SPACE`, `invalid-path`,
+  `name-too-long`) instead of `DSM_FAILED`. New codes: `not-a-file`,
+  `recursive-required`, `recycle-bin-disabled`, `task-not-found`,
+  `too-many-tasks`, `READ_FAILED`.
+
+### Approval
+
+- An administrator approves the executor policy (operations, scope and root
+  tasks), not the executor binary. When an upgrade keeps the policy and the
+  new executor matches the `INFO` anchor, it installs without a new approval.
+  When the policy changes, the App stays at `needs-admin-approval` until an
+  administrator approves again.
+- The 0.9.0 policy changes (new operations and `conflict`), so a delegate App
+  rebuilt with this CLI needs one new approval after the upgrade.
+  Moving the SDK to its own repository does not add one. Apps not rebuilt are
+  not affected.
+
 ## 0.8.0 (2026-10-11)
 
 Faster builds, one SPK checker for any package, and a guide for scripts and

package/README.md

@@ -18,7 +18,7 @@ Native Go apps need Go 1.25+ and npm. The CLI is tested on Node.js 22.19.
 ```sh
 synopkgland init -t native-go --with files,jobs,login --package MyApp my-app
 cd my-app
-(cd frontend && npm ci)
+(cd frontend && npm install)
 synopkgland check --json
 synopkgland build --arch x86_64 --json
 synopkgland inspect dist/MyApp-0.1.0-0001-x86_64.spk --json
@@ -40,6 +40,27 @@ the SPK with Package Center's Manual Install.
 Existing native products with their own payload layout use `backend: {kind: native}` in
 `dsm-package.yaml`.
 
+## SDK and templates
+
+The CLI packages, deploys and checks. The app-side code is the SDK
+([synopackageland/syno-pkg-land-sdk](https://github.com/synopackageland/syno-pkg-land-sdk)): the Go module
+`github.com/synopackageland/syno-pkg-land-sdk` and the npm package `@synopackageland/sdk` (Vue components at
+`@synopackageland/sdk/vue`). The `require github.com/synopackageland/syno-pkg-land-sdk` line in
+`backend/go.mod` is the app's only SDK version; `build` compiles the executor of that version
+and checks it against the digests shipped in this CLI. CLI 0.9.x builds SDK 0.9.x.
+
+The SDK repositories are private for now, so Go cannot fetch them from proxy.golang.org. Set
+`go env -w GOPRIVATE=github.com/synopackageland/*` and give git a credential that can read
+`https://github.com/synopackageland/syno-pkg-land-sdk` (check with `git ls-remote`); a failed
+fetch reports `SDK_DOWNLOAD_FAILED` with the step that is missing.
+
+`init` and `add` read their templates from `@synopackageland/templates`, an exact-pinned
+dependency. For development against local checkouts, set `SYNOPKGLAND_TEMPLATES_DIR` to a
+templates checkout and `SYNOPKGLAND_SDK_DIR` to an SDK checkout; SPKs built with
+`SYNOPKGLAND_SDK_DIR` warn `EXECUTOR_DIGEST_UNVERIFIED` and must not be published. A Vue project
+packs the local SDK into its frontend (`npm install --install-links`) without building it: run
+`npm ci && npm run build` in `$SYNOPKGLAND_SDK_DIR/ts` first, and again after SDK changes.
+
 ## Capabilities
 
 Add them with `init --with …` or later with `synopkgland add <capability…>`.
@@ -86,14 +107,15 @@ UI components and `npx --no syno-pkg-land-ui describe Button --json` describes o
 
 ## Licensing
 
-The CLI and its original templates are MIT licensed, Copyright (c) 2026 synopkgland.
+The CLI is MIT licensed, Copyright (c) 2026 synopkgland.
 Third-party components keep their own terms.
 
 - Generated projects keep the template terms in `LICENSES/TEMPLATE.txt`. `init` does not choose a
   license for your app: add your own `LICENSE`.
 - An SPK carries its legal notices under `LICENSES/` in the installed payload: `TEMPLATE.txt`,
-  an optional `APP.txt`, Go's license, patents and third-party notices, and the Vue UI notices.
-- Vue builds generate the UI notices from the installed, locked dependencies; run `npm ci` in
+  an optional `APP.txt`, `SDK.txt` (the SDK's MIT license, when `backend/go.mod` requires the SDK),
+  Go's license, patents and third-party notices, and the Vue UI notices.
+- Vue builds generate the UI notices from the installed dependencies; run `npm install` in
   `frontend/` first. A missing notice or version mismatch fails the build.
 - Keep `backend/THIRD_PARTY_NOTICES.txt` current when you change Go modules. Your own binaries,
   added modules, container images and upstream apps need their own notices.

package/dist/add.js

@@ -5,19 +5,9 @@ import { isScalar, parseDocument } from 'yaml';
 import { capabilityNames, capabilitySettings } from './capabilities.js';
 import { initFromTemplate, nativeCapabilitySettings } from './init.js';
 import { templatesRoot } from './template-paths.js';
+import { borrowedTarget, capabilityOverlays } from './capability-overlays.js';
 import { DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_MIN_DSM } from './build-spk/dsm-version.js';
 import { loadStandaloneManifest } from './standalone/manifest.js';
-const overlays = {
-    jobs: ['native-go-jobs'],
-    'root-ops': ['native-go-root-ops'],
-    delegate: ['native-go-jobs', 'native-go-delegate'],
-    files: ['native-go-files'], login: ['native-go-identity'],
-};
-const removed = {
-    jobs: ['backend/internal/app/background_none.go'],
-    'root-ops': ['backend/internal/app/root_none.go'],
-    delegate: ['backend/internal/app/background_none.go', 'backend/internal/app/root_none.go', 'backend/internal/app/delegate_none.go'],
-};
 function files(root, dir = root) {
     if (!existsSync(dir))
         return [];
@@ -106,12 +96,9 @@ export function addCapabilities(root, requested) {
         const before = join(work, 'before'), generated = join(work, 'generated');
         initFromTemplate('native-go', before, { ui: m.ui.build ? 'vue' : 'plain', with: existingNames, packageId: m.package, displayName: m.displayname });
         initFromTemplate('native-go', generated, { ui: m.ui.build ? 'vue' : 'plain', with: [...existingNames, ...added], packageId: m.package, displayName: m.displayname });
-        const destinations = [...new Set(added.flatMap(name => overlays[name].flatMap(overlay => files(join(templatesRoot(), overlay)))))].filter(file => existsSync(join(generated, file)));
-        if (added.includes('delegate'))
-            destinations.push('backend/internal/background/store.go', 'backend/internal/app/executor.go', 'backend/internal/app/executor_test.go', 'backend/internal/api/sdk-permissions.json');
-        if (added.includes('jobs') || added.includes('delegate') || added.includes('root-ops'))
-            destinations.push('backend/internal/app/routes_test.go');
-        const deletions = added.flatMap(name => removed[name] ?? []);
+        const capability = capabilityOverlays(added);
+        const destinations = [...new Set([...capability.overlays.flatMap(overlay => files(join(templatesRoot(), overlay))), ...capability.borrowed.map(borrowedTarget)])].filter(file => existsSync(join(generated, file)));
+        const deletions = capability.removed;
         const conflicts = [];
         for (const file of destinations) {
             if (existsSync(join(before, file)) && safePath(root, file) && existsSync(join(root, file)) && lstatSync(join(root, file)).isFile() && readFileSync(join(root, file)).equals(readFileSync(join(before, file))))

package/dist/authorization-sdk.d.ts

@@ -4,4 +4,3 @@
  */
 export { ROOT_RUNTIME, type RootTask } from './standalone/native-root-window.js';
 export { AUTHORIZATION_RUNTIME } from './standalone/native-authorization-window.js';
-export declare const authorizationTemplateDirectory: URL;

package/dist/authorization-sdk.js

@@ -4,4 +4,3 @@
  */
 export { ROOT_RUNTIME } from './standalone/native-root-window.js';
 export { AUTHORIZATION_RUNTIME } from './standalone/native-authorization-window.js';
-export const authorizationTemplateDirectory = new URL('../templates/native-authorization/', import.meta.url);

package/dist/build-spk/gateway.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { checkCgiBinary } from "../standalone/binary.js";
 import { runCommand } from "../standalone/build.js";
 import { resolvedWebAccess } from "../contract/web-launch.js";
-import { templatesRoot } from "../template-paths.js";
+import { goAssetDir } from "../template-paths.js";
 import { PINNED_GO_HINT, pinnedGoBuildEnv, pinnedGoProblem } from "./go-toolchain.js";
 export { gatewayEntryPath } from "../contract/web-launch.js";
 /** Where the gateway CGI sits in the package payload; DSM serves `ui/` under /webman/3rdparty/<package>/. */
@@ -28,7 +28,7 @@ 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 = await (input.run ?? runCommand)("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, "."], {
-        cwd: join(templatesRoot(), "_gateway"),
+        cwd: goAssetDir("gateway"),
         env: { ...process.env, ...pinnedGoBuildEnv(input.arch) },
     });
     if (result.missing) {

package/dist/build-spk/notices.js

@@ -1,5 +1,6 @@
 import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { sdkRequirement, sdkSource } from '../runtime/sdk-source.js';
 /** Copy legal text only; never follow a project-supplied symlink. */
 export function copyNoticeTree(source, target) {
     const stat = lstatSync(source);
@@ -28,7 +29,7 @@ export function copyProjectNotices(root, payload) {
 export function copyStandaloneNotices(root, uiDir, payload, go, goDir = join(root, 'backend')) {
     copyProjectNotices(root, payload);
     const dest = join(payload, 'LICENSES');
-    const shared = new URL('../../templates/_shared/', import.meta.url);
+    const shared = new URL('../../assets/licenses/', import.meta.url);
     if (go) {
         mkdirSync(dest, { recursive: true });
         for (const name of ['GO-LICENSE', 'GO-PATENTS'])
@@ -36,14 +37,17 @@ export function copyStandaloneNotices(root, uiDir, payload, go, goDir = join(roo
         if (existsSync(join(goDir, 'THIRD_PARTY_NOTICES.txt')))
             copyNoticeTree(join(goDir, 'THIRD_PARTY_NOTICES.txt'), join(dest, 'GO-THIRD_PARTY_NOTICES.txt'));
     }
-    const nativeAdmin = join(goDir, 'internal/dsm/native');
-    if (go && existsSync(join(nativeAdmin, 'admin_check.c'))) {
-        for (const name of ['admin_check.c', 'apppriv_check.c', 'build.sh', 'provenance.json', 'licenses']) {
-            // Projects scaffolded before the AppPriv bridge carry only the administrator bridge.
-            if (name === 'apppriv_check.c' && !existsSync(join(nativeAdmin, name)))
-                continue;
+    // The SDK's dsm package embeds the native administrator and AppPriv bridges; their sources and terms ship with them.
+    const sdk = go ? sdkRequirement(goDir) : undefined;
+    if (sdk) {
+        const source = sdkSource(sdk);
+        const license = join(source.goDir, 'LICENSE');
+        if (!existsSync(license))
+            throw new Error(`[NOTICE_MISSING] SDK license missing: ${license}`);
+        copyNoticeTree(license, join(dest, 'SDK.txt'));
+        const nativeAdmin = join(source.goDir, 'dsm/native');
+        for (const name of ['admin_check.c', 'apppriv_check.c', 'build.sh', 'provenance.json', 'licenses'])
             copyNoticeTree(join(nativeAdmin, name), join(dest, 'native-admin', name));
-        }
     }
     const frontend = join(root, 'frontend/package.json');
     const usesUi = existsSync(frontend) && Boolean(JSON.parse(readFileSync(frontend, 'utf8')).dependencies?.['@synopackageland/ui']);

package/dist/capability-overlays.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How each native-go capability is laid over the base template: the template
+ * directories copied on top, files borrowed from another overlay, and the
+ * base files the overlay replaces. init and add both read this table.
+ */
+export interface CapabilityOverlay {
+    overlays: string[];
+    borrowed: string[];
+    removed: string[];
+}
+export declare const CAPABILITY_OVERLAYS: Record<string, CapabilityOverlay>;
+/** The overlays of these capabilities, in table order, each once; a capability without one adds nothing. */
+export declare function capabilityOverlays(names: readonly string[]): CapabilityOverlay;
+/** A borrowed path names its overlay first; this is where it lands in a project. */
+export declare const borrowedTarget: (path: string) => string;

package/dist/capability-overlays.js

@@ -0,0 +1,18 @@
+const EXECUTOR_SHELL = ['backend/internal/app/executor.go', 'backend/internal/app/executor_test.go'];
+export const CAPABILITY_OVERLAYS = {
+    'root-ops': { overlays: ['native-go-root-ops'], borrowed: [], removed: ['backend/internal/app/root_none.go'] },
+    jobs: { overlays: ['native-go-jobs'], borrowed: [], removed: ['backend/internal/app/background_none.go'] },
+    delegate: {
+        overlays: ['native-go-jobs', 'native-go-delegate'],
+        borrowed: EXECUTOR_SHELL.map(file => `native-go-root-ops/${file}`),
+        removed: ['backend/internal/app/background_none.go', 'backend/internal/app/root_none.go', 'backend/internal/app/delegate_none.go'],
+    },
+};
+/** The overlays of these capabilities, in table order, each once; a capability without one adds nothing. */
+export function capabilityOverlays(names) {
+    const chosen = Object.entries(CAPABILITY_OVERLAYS).filter(([name]) => names.includes(name)).map(([, overlay]) => overlay);
+    const unique = (pick) => [...new Set(chosen.flatMap(pick))];
+    return { overlays: unique(o => o.overlays), borrowed: unique(o => o.borrowed), removed: unique(o => o.removed) };
+}
+/** A borrowed path names its overlay first; this is where it lands in a project. */
+export const borrowedTarget = (path) => path.split('/').slice(1).join('/');

package/dist/cli-version.d.ts

@@ -0,0 +1,2 @@
+/** This CLI's own release, read from its package.json. */
+export declare const CLI_VERSION: string;

package/dist/cli-version.js

@@ -0,0 +1,3 @@
+import { readFileSync } from "node:fs";
+/** This CLI's own release, read from its package.json. */
+export const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;

package/dist/cli.js

@@ -118,6 +118,7 @@ async function standaloneBuild(root, arches, options) {
     const result = isNativeLayout(root)
         ? 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;
@@ -306,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...>")

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",
@@ -695,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 字）。"],
@@ -706,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.js

@@ -9,9 +9,9 @@ import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { extractSpk, walkFiles } from "./build-spk/generator.js";
 import { invalid, readReproducible } from "./reproducible-config.js";
+import { CLI_VERSION } from "./cli-version.js";
 export { readReproducible, validateReproducible } from "./reproducible-config.js";
 export const FINGERPRINT_RECORD = "reproducible-fingerprint.json";
-const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
 function insideProject(root, path) {
     const rel = relative(realpathSync(root), realpathSync(path));