@synopackageland/cli 0.3.1 → 0.3.2

package/dist/templates/hello-web-page/compose.yaml

@@ -1,7 +1,18 @@
 services:
   web:
-    image: nginx:alpine
+    image: busybox:1.36
+    # 兩個平台限制，改動前先看 docs/impl/STATUS.md 的 2026-08-24 段：
+    # 1) command／entrypoint 陣列不得有純數字元素（例如 "18333"）。DSM 的
+    #    docker-project worker 會在 YAML round-trip 時掉引號、把它變成整數，
+    #    postinst acquire 直接失敗（error 276 → 套件 broken/150，且 worker_msg
+    #    為空，開發者看不到原因）。所以 port 要包在單一字串裡。
+    #    `synopkgland validate` 已會擋這個寫法。
+    # 2) 預設不用 8080：那個 port 在真實 NAS 上很常被既有容器占用，而 port
+    #    衝突同樣以那個看不出原因的 broken/150 呈現。
+    # 官方 nginx image 也不能用：resource worker 注入任意 package UID/GID，
+    # nginx entrypoint 啟動階段需要 root，會在該身分下直接退出。
+    command: ["sh","-c","httpd -f -p 18333 -h /usr/share/nginx/html"]
     ports:
-      - "8080:80"
+      - "18333:18333"
     volumes:
-      - "${SYNOPKG_PKGVAR}/html:/usr/share/nginx/html:ro"
+      - "./html:/usr/share/nginx/html:ro"

package/dist/templates/hello-web-page/synology-app.yaml

@@ -6,7 +6,7 @@ description: A Syno Package Land web app template that opens in a new browser pa
 maintainer: Syno Package Land
 os_min_ver: "7.2-69057"
 adminprotocol: http
-adminport: 8080
+adminport: 18333
 adminurl: /
 integration:
   web:

package/dist/test-host.d.ts

@@ -8,6 +8,8 @@ export interface TestProjectOnHostOptions {
 }
 export interface TestProjectOnHostResult {
     ok: boolean;
+    code?: string;
     message?: string;
+    suggestion?: string;
 }
 export declare function testProjectOnHost(options: TestProjectOnHostOptions): Promise<TestProjectOnHostResult>;

package/dist/test-host.js

@@ -3,14 +3,22 @@ import { resolveDeployIdentity } from "./deploy/identity.js";
 export async function testProjectOnHost(options) {
     const validation = validateProject(options.project);
     if (!validation.ok) {
-        return { ok: false, message: validation.errors.map((e) => e.code).join(", ") };
+        const firstCode = validation.errors[0]?.code ?? "VALIDATION_FAILED";
+        return {
+            ok: false,
+            code: firstCode,
+            message: validation.errors.map((e) => e.code).join(", "),
+            suggestion: "請修正合約與 Compose 錯誤。",
+        };
     }
     const identity = resolveDeployIdentity(options.project, { dev: options.dev });
     const installed = await options.host.isPackageInstalled(identity.packageId);
     if (!installed) {
         return {
             ok: false,
+            code: "NOT_INSTALLED",
             message: `尚未部署到 ${options.host.dsmOrigin}。下一步：synopkgland deploy --host <nas>${options.dev ? " --dev" : ""}`,
+            suggestion: `請執行 synopkgland deploy --host <nas>${options.dev ? " --dev" : ""} 先行部署。`,
         };
     }
     const smoke = await options.host.smokeRequireLogin({
@@ -18,7 +26,12 @@ export async function testProjectOnHost(options) {
         cookieHeader: options.cookieHeader ?? "id=fake; did=fake",
     });
     if (!smoke.ok) {
-        return { ok: false, message: "Open smoke 失敗：requireLogin 未取得 DSM 使用者。" };
+        return {
+            ok: false,
+            code: "TEST_HOST_FAILED",
+            message: "Open smoke 失敗：requireLogin 未取得 DSM 使用者。",
+            suggestion: "請確認應用程式前端已正確初始化 SDK 並登入 DSM。",
+        };
     }
     return { ok: true };
 }

package/dist/types.d.ts

@@ -33,7 +33,7 @@ export interface AppContract {
     [key: string]: unknown;
 }
 export interface InstallParameter {
-    type?: string;
+    type?: "string" | "boolean" | "secret" | "shared_folder" | "dsm_user" | "homes" | string;
     default?: unknown;
     generate?: boolean;
 }

package/dist/validate.js

@@ -2,11 +2,12 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { collectInstallParameters, loadContract } from "./contract/load.js";
 import { validateContract } from "./contract/validate.js";
-import { collectComposeInterpolations, collectVolumeSourceInterpolations, loadCompose, validateAdminPortMapping, validateComposeHostBinds, validateComposeRunAs, validateComposeSecurity, } from "./compose/analyze.js";
+import { collectComposeInterpolations, collectVolumeSourceInterpolations, loadCompose, validateAdminPortMapping, validateComposeHostBinds, validateComposeNumericCommandArgs, validateComposeRunAs, validateComposeSecurity, } from "./compose/analyze.js";
 import { loadNative } from "./native/load.js";
 import { validateNative } from "./native/validate.js";
 import { COMPOSE_FILENAME, CONTRACT_FILENAME, NATIVE_FILENAME, } from "./discovery.js";
 import { declaredPrivilegeFlags } from "./compose/privilege.js";
+import { resourceWorkerEligibility } from "./build-spk/resource-worker.js";
 export function validateProject(project, options = {}) {
     const profile = options.profile ?? "personal";
     const errors = [];
@@ -61,11 +62,16 @@ export function validateProject(project, options = {}) {
         profile,
         declaredPrivilege: declaredPrivilegeFlags(parsed.contract),
     }));
+    if (resourceWorkerEligibility(parsed.contract, parsedCompose.compose).eligible) {
+        errors.push(...validateComposeNumericCommandArgs(parsedCompose.compose, composeFile));
+    }
     const installParams = collectInstallParameters(parsed.contract);
     const sharedFolderParams = new Set(installParams.filter(({ param }) => param.type === "shared_folder").map(({ name }) => name));
+    const homesParams = new Set(installParams.filter(({ param }) => param.type === "homes").map(({ name }) => name));
     const installParamNames = new Set(installParams.map(({ name }) => name));
     errors.push(...validateComposeHostBinds(parsedCompose.compose, composeFile, {
         sharedFolderParams,
+        homesParams,
         installParamNames,
     }));
     if (typeof parsed.contract.adminport === "number") {
@@ -96,8 +102,13 @@ export function validateProject(project, options = {}) {
         ? { ...item, severity: (profile === "listing" ? "error" : "warning") }
         : item));
     for (const { name, param } of installParams) {
-        const referenced = param.type === "shared_folder" ? volumeSourceVars.has(name) : interpolations.has(name);
-        if ((param.type === "string" || param.type === "boolean" || param.type === "shared_folder") &&
+        const referenced = param.type === "shared_folder" || param.type === "homes"
+            ? volumeSourceVars.has(name)
+            : interpolations.has(name);
+        if ((param.type === "string" ||
+            param.type === "boolean" ||
+            param.type === "shared_folder" ||
+            param.type === "homes") &&
             !referenced) {
             errors.push({
                 code: "INSTALL_PARAMETER_UNREFERENCED",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@synopackageland/dev-sdk": "^0.2.0",
-    "@synopackageland/package-source": "^0.2.0",
+    "@synopackageland/package-source": "^0.2.1",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "jose": "^6.0.10",

package/schema/doctor.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SynoPkgLandDoctorReport",
+  "type": "object",
+  "required": ["ok", "checks"],
+  "additionalProperties": false,
+  "properties": {
+    "ok": {
+      "type": "boolean"
+    },
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "status", "message"],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pass", "fail", "skip"]
+          },
+          "code": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "suggestion": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/synology-app.schema.json

@@ -59,7 +59,7 @@
         "properties": {
           "type": {
             "type": "string",
-            "enum": ["string", "boolean", "secret", "shared_folder", "dsm_user"]
+            "enum": ["string", "boolean", "secret", "shared_folder", "dsm_user", "homes"]
           },
           "default": {},
           "generate": {

package/skills/reference/create.md

@@ -17,6 +17,25 @@ synopkgland init -t hello-web [目錄]
 
 產物：`synology-app.yaml`、`compose.yaml`、README。需要程式碼時在同一專案加最小 Web App；v1 官方範例用 TypeScript + `@synopackageland/dev-sdk`。
 
+## Published port 分配
+
+`hello-web` 與 `hello-web-page` 模板的預設 `adminport` 是 **18333**。這個預設值在 2026-08-24 由 8080 調整而來，因為 8080 在真實 NAS 上常被既有容器使用；它只降低碰撞機率，不能保證該 port 一定可用。
+
+`adminport` 是 NAS 上的 published host port，必須和 `compose.yaml` 的 host-side published port 對應。若同一台 NAS 上有多個測試或正式 instance，每個 package／instance 都要分配獨立的 published port；**同一台 NAS 上不要重用同一個 port**。可挑選尚未被既有服務使用的高位 port，例如 19xxx 範圍（`19160` 只是示例），並記錄每個 instance 的分配。
+
+例如把模板 instance 改用 19160 時，`synology-app.yaml` 與 Compose 的 host-side port 要一起改，容器內 target 仍依原本 Compose／映像設定：
+
+```yaml
+# synology-app.yaml
+adminport: 19160
+
+# compose.yaml
+ports:
+  - "19160:18333"
+```
+
+不要只改其中一處：`adminport` 沒有對應的 published port 會在 `validate` 被擋下；host port 已被同一台 NAS 的其他服務占用，則可能直到 deploy 才以 DSM 的 `broken` 呈現。
+
 包現成 Compose 時，先用 `inspect` 看原本的 volume mapping。容器路徑跟 Compose／映像的 upstream target 走，不要為了套平台範例改成 `/data`；只把 host source 換成 `${PARAM}`。原有的 upstream named volume 要保留在頂層 `volumes:`。需要既有 Share 時宣告 `install.<PARAM>.type: shared_folder`，管理員在安裝時選這台 NAS 的 Share。
 
 ## 只問這些（缺才問）

package/skills/reference/diagnose.md

@@ -1,6 +1,38 @@
 # 排查（Diagnose）
 
-依 **穩定錯誤碼** 行動；權威是 `synopkgland validate` 輸出、`deploy`／Broker 回傳、`info`／`log` 的 readiness。不要猜 Compose。
+遇到問題時，**先跑 `synopkgland doctor`，依穩定錯誤碼行動**。
+
+```bash
+# 診斷本機專案（契約、Compose/Native 設定、版本漂移）
+synopkgland doctor
+
+# 診斷目標 NAS 主機（連線、Broker 狀態、Container Manager、Attestation 信任根）
+synopkgland doctor --host <nas>
+
+# 診斷特定 App 套件（Project Binding 狀態、上次安裝/就緒失敗原因、入口探測）
+synopkgland doctor --host <nas> --package <id>
+```
+
+權威是 `synopkgland doctor` 診斷檢查、`synopkgland validate` 輸出、`deploy`／Broker 回傳與 `info`／`log` 的 readiness。所有 fail 項均帶有穩定錯誤碼與具體的下一步建議。不要猜 Compose。
+
+## deploy 後 `broken`／statusCode 150
+
+若 deploy 回報 `CATALOG_INSTALL_FAILED`，而 DSM 顯示 `[CATALOG_INSTALL_FAILED] ... (Package Center status broken). Check synopkg postinst / webservice acquire.`，先跑：
+
+```bash
+synopkgland doctor --host <nas> --package <id>
+```
+
+這類失敗可能只有 `broken_by=install_corruption`／`statusCode=150`，DSM 的錯誤訊息通常看不出真正原因。先依 `doctor` 的建議排查以下兩項：
+
+| 常見原因 | 修法 |
+| --- | --- |
+| 同一台 NAS 上已有其他服務或 instance，published host port 已被占用 | 為每個 package／instance 分配不重複的 host port，例如改用 19160；同步把 `synology-app.yaml` 的 `adminport` 改成 19160，並把 `compose.yaml` 的 host-side mapping 改成例如 `"19160:18333"`。容器內 target 依原本 Compose／映像設定保留。 |
+| Compose `command`／`entrypoint` 陣列含純數字字串元素，例如 `"18333"` | 若走 resource-worker 路徑，`validate` 會報 `COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN`。把整個命令包成單一字串，例如 `command: ["sh","-c","httpd -f -p 18333 -h /srv"]`，或把數字和 flag 併寫成 `-p18333`。 |
+
+第一項是 published port 碰撞；第二項是 DSM 的 resource-worker 在 YAML round-trip 時掉引號，將純數字元素變成整數，導致 postinst acquire 失敗，可能同樣呈現 `broken`／150，且 `worker_msg` 為空。`COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN` **只適用於 Compose 走 resource-worker 路徑**；純數字元素在標準 Compose 合法，Broker fallback 不受此限制，這是 DSM worker 的缺陷而不是 Compose 規格不允許。
+
+修正後依序執行 `synopkgland validate`，再用 `synopkgland deploy --host <nas>` 重試；若仍失敗，保留 `doctor`、`info` 與 `log` 的診斷輸出供後續判斷。
 
 ## validate／analyzer（修契約或 Compose）
 
@@ -40,7 +72,8 @@
 | `INNER_LOOP_API_MISSING` | 升級 NAS 上 SynoPkgLandService（>=0.1.0-0016）；確認 CGI 非 HTML 404 |
 | `ATTESTATION_FAILED` | 讀 Broker 訊息；常見 digest／身分衝突，必要時 `info --host` 看 attestation |
 | `BUILD_SPK_FAILED` | 修契約／compose 後重試 |
-| `CATALOG_PUBLISH_FAILED`／`CATALOG_INSTALL_FAILED` | Package Source／網路；`info` 看是否已裝；勿手動拼 SPK 上架 |
+| `CATALOG_PUBLISH_FAILED` | Package Source／網路；`info` 看是否已裝；勿手動拼 SPK 上架 |
+| `CATALOG_INSTALL_FAILED`／DSM `broken`／150 | 先跑 `doctor --host <nas> --package <id>`；檢查 published port 碰撞與 `COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN` |
 
 ## info／log／test --host
 

package/skills/reference/files.md

@@ -7,6 +7,16 @@ Personal App **預設較窄**：
 1. Compose 管理的 App Data（`${SYNOPKG_PKGVAR}` 等平台路徑）。
 2. 管理員在安裝時用 Package Center 原生 Share 選擇器，從**這台 NAS**挑 **Shared Folder Mount**（`install.<NAME>.type: shared_folder`）。有 Share 時還要選一個 DSM 使用者當 **Container Run-as**（`install.<NAME>.type: dsm_user`）。容器路徑跟 Compose／映像的 upstream target 走；包現成映像時尤其不要改成平台範例的 `/data`，也不要把 upstream 的 `user: "0:0"` 留著去寫 Share。
 
+### App Data、App Secret 位置與備份提醒
+
+在 Synology NAS 上，資料與生命週期分為三類：
+
+- **App Data**：位於 SPK 原生 package `var`（`/var/packages/<package>/var` → `/volume?/@appdata/<package>`），保存 App 自身資料庫與設定檔。Normal uninstall 預設保留，只有在 Package Center 卸載時明確勾選「Delete App Data」才會刪除。
+- **App Secret**：位於 package `home` 的受限子目錄 `/var/packages/<package>/home/secrets`（權限 0700/0600），由 Compose secret mount 掛載。Normal uninstall 預設保留，重裝同一個 Package Identity 時優先重用同名 secret。
+- **Shared Folder Mount**：由 NAS Administrator 在安裝時挑選的 DSM 共用資料夾（`/volume?/<ShareName>`）。寫入權限由 Container Run-as 使用者決定；平台 lifecycle 絕不刪除或修改其內容。
+
+> **Named Volume 警告**：若第三方 Compose 使用 Docker named volume（如 `volumes: [ "my-data:/data" ]`），其生命週期完全由 Container Manager 管理，**不在** Syno Package Land 平台的保留、備份或清理承諾範圍內。需要持久化時請改用 package `var` 或 Shared Folder Mount。
+
 ### 包現成 Compose
 
 - volume mapping 右側的 container target 與 `ro`／`rw` 是映像／upstream 的契約，保留原值；只把左側 host source 換成 `${NAME}`，並在 App Contract 宣告對應的 `shared_folder` 槽。

package/templates/hello-files/compose.yaml

@@ -4,5 +4,7 @@ services:
     command: ["sleep", "infinity"]
     user: "${RUN_AS_UID}:${RUN_AS_GID}"
     volumes:
+      # Dynamic Shared Folder plus writable /state is Broker-managed and is
+      # intentionally outside the zero-config docker-project resource-worker path.
       - "${MEDIA_SHARE}/data:/data:ro"
       - "${SYNOPKG_PKGVAR}/state:/state"

package/templates/hello-web/compose.yaml

@@ -1,7 +1,18 @@
 services:
   web:
-    image: nginx:alpine
+    image: busybox:1.36
+    # 兩個平台限制，改動前先看 docs/impl/STATUS.md 的 2026-08-24 段：
+    # 1) command／entrypoint 陣列不得有純數字元素（例如 "18333"）。DSM 的
+    #    docker-project worker 會在 YAML round-trip 時掉引號、把它變成整數，
+    #    postinst acquire 直接失敗（error 276 → 套件 broken/150，且 worker_msg
+    #    為空，開發者看不到原因）。所以 port 要包在單一字串裡。
+    #    `synopkgland validate` 已會擋這個寫法。
+    # 2) 預設不用 8080：那個 port 在真實 NAS 上很常被既有容器占用，而 port
+    #    衝突同樣以那個看不出原因的 broken/150 呈現。
+    # 官方 nginx image 也不能用：resource worker 注入任意 package UID/GID，
+    # nginx entrypoint 啟動階段需要 root，會在該身分下直接退出。
+    command: ["sh","-c","httpd -f -p 18333 -h /usr/share/nginx/html"]
     ports:
-      - "8080:80"
+      - "18333:18333"
     volumes:
-      - "${SYNOPKG_PKGVAR}/html:/usr/share/nginx/html:ro"
+      - "./html:/usr/share/nginx/html:ro"

package/templates/hello-web/synology-app.yaml

@@ -6,7 +6,7 @@ description: A minimal Syno Package Land web app template.
 maintainer: Syno Package Land
 os_min_ver: "7.2-69057"
 adminprotocol: http
-adminport: 8080
+adminport: 18333
 adminurl: /
 integration:
   web:

package/templates/hello-web-page/compose.yaml

@@ -1,7 +1,18 @@
 services:
   web:
-    image: nginx:alpine
+    image: busybox:1.36
+    # 兩個平台限制，改動前先看 docs/impl/STATUS.md 的 2026-08-24 段：
+    # 1) command／entrypoint 陣列不得有純數字元素（例如 "18333"）。DSM 的
+    #    docker-project worker 會在 YAML round-trip 時掉引號、把它變成整數，
+    #    postinst acquire 直接失敗（error 276 → 套件 broken/150，且 worker_msg
+    #    為空，開發者看不到原因）。所以 port 要包在單一字串裡。
+    #    `synopkgland validate` 已會擋這個寫法。
+    # 2) 預設不用 8080：那個 port 在真實 NAS 上很常被既有容器占用，而 port
+    #    衝突同樣以那個看不出原因的 broken/150 呈現。
+    # 官方 nginx image 也不能用：resource worker 注入任意 package UID/GID，
+    # nginx entrypoint 啟動階段需要 root，會在該身分下直接退出。
+    command: ["sh","-c","httpd -f -p 18333 -h /usr/share/nginx/html"]
     ports:
-      - "8080:80"
+      - "18333:18333"
     volumes:
-      - "${SYNOPKG_PKGVAR}/html:/usr/share/nginx/html:ro"
+      - "./html:/usr/share/nginx/html:ro"

package/templates/hello-web-page/synology-app.yaml

@@ -6,7 +6,7 @@ description: A Syno Package Land web app template that opens in a new browser pa
 maintainer: Syno Package Land
 os_min_ver: "7.2-69057"
 adminprotocol: http
-adminport: 8080
+adminport: 18333
 adminurl: /
 integration:
   web: