@synopackageland/cli 0.1.0

package/schema/synology-app.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://synology.dev/schemas/synology-app/1",
+  "title": "Synology App Contract",
+  "description": "App Contract schema version 1 for synology-app.yaml",
+  "type": "object",
+  "required": [
+    "schema",
+    "package",
+    "version",
+    "displayname",
+    "description",
+    "maintainer",
+    "os_min_ver"
+  ],
+  "properties": {
+    "schema": {
+      "type": "integer",
+      "const": 1,
+      "description": "App Contract schema version; v1 only accepts integer 1"
+    },
+    "package": {
+      "type": "string",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "displayname": {
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1
+    },
+    "maintainer": {
+      "type": "string",
+      "minLength": 1
+    },
+    "os_min_ver": {
+      "type": "string",
+      "minLength": 1
+    },
+    "adminprotocol": {
+      "type": "string"
+    },
+    "adminport": {
+      "type": "integer"
+    },
+    "adminurl": {
+      "type": "string"
+    },
+    "install": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["string", "boolean", "secret", "shared_folder", "dsm_user"]
+          },
+          "default": {},
+          "generate": {
+            "type": "boolean"
+          }
+        },
+        "required": ["type"]
+      }
+    },
+    "integration": {
+      "type": "object",
+      "properties": {
+        "web": {
+          "type": "object",
+          "properties": {
+            "launch": {
+              "type": "string",
+              "enum": ["dsm-window", "new-page"],
+              "description": "Web App Launch Mode. dsm-window opens a DSM Application Window at the Trusted App Entry; new-page uses Package Center Open. Omit for dsm-window. Headless apps omit this field."
+            },
+            "cookies": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Optional App cookie name allowlist forwarded by the generated Web Station ingress. Omit to forward no browser cookies."
+            }
+          },
+          "additionalProperties": true
+        },
+        "identity": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode"],
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["broker-managed"],
+              "description": "v1 identity mode. SDK Apps omit oidc_compat; wrap-existing may add it."
+            },
+            "oidc_compat": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["redirect_path"],
+              "properties": {
+                "redirect_path": {
+                  "type": "string",
+                  "pattern": "^/(?!/)(?!.*\\.\\.)[^\\s?#:]*$",
+                  "description": "App-owned OIDC callback path. No scheme, host, query, or '..'."
+                }
+              }
+            }
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "permissions": {
+      "type": "object"
+    },
+    "privilege": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "privileged": { "type": "boolean" },
+        "host_network": { "type": "boolean" },
+        "host_pid": { "type": "boolean" },
+        "host_ipc": { "type": "boolean" },
+        "devices": { "type": "boolean" },
+        "cap_add": { "type": "boolean" }
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/skills/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: synopkgland
+description: Agent Authoring for Syno Package Land — create, validate, and Inner Loop deploy a Personal App to the author's NAS with synopkgland CLI. Load when the user wants to build a DSM app from a brief, scaffold from templates, validate App Contract + Compose, deploy with Local Attestation, or diagnose analyzer/deploy/readiness failures. Not for Curated publish, SSH to NAS, or inventing platform fields.
+version: 0.1.0
+---
+
+Syno Package Land Skill Pack（與 `@synopackageland/cli` 同版本、同 repo，不另發 npm）。
+
+## 載入方式
+
+1. 執行 `synopkgland skill path`，得到 Skill Pack 根目錄。
+2. **永遠先讀**本檔 `SKILL.md`。
+3. 依任務載入 `reference/*.md`（見下表）。不要一次讀完全部。
+
+| 階段 | 檔案 | 何時 |
+| --- | --- | --- |
+| 建立 | `reference/create.md` | 從零或一句話需求 |
+| 封裝 | `reference/wrap.md` | 已有 `compose.yaml` 或要補契約 |
+| 身分 | `reference/identity.md` | 需要 DSM 登入／Open |
+| 檔案 | `reference/files.md` | 需要 NAS 檔案 |
+| 部署 | `reference/deploy.md` | 要 `deploy` 到 NAS |
+| 排查 | `reference/diagnose.md` | `validate`／`deploy`／Open 失敗 |
+
+也可用 `synopkgland skill list`、`synopkgland skill show <id>` 在終端機檢視。
+
+## 權威邊界（必守）
+
+- **權威**：`synology-app.yaml` schema（`packages/app-cli/schema/synology-app.schema.json`）、`synopkgland validate`／analyzer 錯誤碼、repo 測試。Skill 只是操作介面。
+- **禁止發明欄位**：不得新增 schema 沒有的 top-level 或 `install` 型別；不得自創第二套 Compose／SPK DSL。不確定時先 `synopkgland inspect` 或讀模板，再 `validate`。
+- **禁止洩漏 secret**：不得把 DSM 密碼、signing key、API token 寫進 Git、`compose.yaml` environment、`.env` commit、或對話紀錄。NAS 憑證用 synoagentcli profile 或本機環境變數，由 CLI 讀取。
+- **不要讀 ADR** 當預設步驟；需要決策時 skill 才指向規格。
+- **不要宣稱** 15 分鐘黃金路徑已通過、公開 SDK 已 freeze、或 `inner-loop` 全綠。
+
+## 典型流程
+
+```text
+一句話需求
+  → reference/create.md（選模板、最少問題）
+  → synopkgland init -t hello-web|hello-web-page|hello-files|compose-import
+  → synopkgland dev（本機 mock）
+  → synopkgland validate
+  → synopkgland test
+  → reference/deploy.md → synopkgland deploy --host <nas>
+  → synopkgland info --host <nas>；DSM Open
+```
+
+失敗時載入 `reference/diagnose.md`；依錯誤碼修契約或 Compose，**不要猜**。
+
+## CLI 專案根
+
+`synopkgland` 從 cwd 向上找 `synology-app.yaml`，或 `--project <dir>`。v1 不做 monorepo workspace 協定。

package/skills/reference/create.md

@@ -0,0 +1,34 @@
+# 建立（Create）
+
+從一句話或空白目錄產出可跑專案。**最少問題**：只問 schema／模板無法推斷的意圖。
+
+## 選模板（`synopkgland init -t`）
+
+| 模板 | 何時 | 預設整合 |
+| --- | --- | --- |
+| `hello-web` | 第一個「DSM 帳號打開」的 Web App（DSM 視窗） | 身分；`launch: dsm-window`；**不**開廣域 `files.*` |
+| `hello-web-page` | Web App 以 Package Center Open 開新分頁 | 身分；`launch: new-page` |
+| `hello-files` | 讀寫管理員選的 Shared Folder | 身分 + 必填 `install` shared_folder |
+| `compose-import` | 已有 `compose.yaml` | 保留映像／upstream 的 container target；只把 host source 換成 `${PARAM}`；Share 安裝時選 |
+
+```bash
+synopkgland init -t hello-web [目錄]
+```
+
+產物：`synology-app.yaml`、`compose.yaml`、README。需要程式碼時在同一專案加最小 Web App；v1 官方範例用 TypeScript + `@synopackageland/dev-sdk`。
+
+包現成 Compose 時，先用 `inspect` 看原本的 volume mapping。容器路徑跟 Compose／映像的 upstream target 走，不要為了套平台範例改成 `/data`；只把 host source 換成 `${PARAM}`。原有的 upstream named volume 要保留在頂層 `volumes:`。需要既有 Share 時宣告 `install.<PARAM>.type: shared_folder`，管理員在安裝時選這台 NAS 的 Share。
+
+## 只問這些（缺才問）
+
+1. **Package Identity**（reverse-DNS，例如 `com.example.myapp`）— 將來上架同一條身分。
+2. **顯示名稱**（`displayname`）。
+3. **要不要碰 NAS 檔案** — 若要，預設走 Shared Folder（`hello-files`），不要默默加 `files.read`／`files.write`／`files.delete`（見 `files.md`）。
+4. **已有 Compose 嗎** — 有則 `compose-import` + `inspect`。
+
+不要問：SPK INFO、wizard、DDNS、port forwarding、Community PR。
+
+## 下一步
+
+- 本機：`synopkgland dev` → `validate` → `test`
+- 要上 NAS：讀 `deploy.md`

package/skills/reference/deploy.md

@@ -0,0 +1,41 @@
+# 部署（Deploy）
+
+Inner Loop：thin SPK、NAS Administrator DSM 授權、Local Attestation、經 Package Center 安裝。**不要 SSH**，不要把 Compose 貼進 Container Manager 手工裝。
+
+## 前置
+
+```bash
+synopkgland validate
+synopkgland test
+```
+
+NAS 需已安裝 **SynoPkgLandService**（Broker）與 Container Manager。CLI 憑證：`synoagentcli` profile 或 `DSM_URL`／`DSM_PASSWORD`（**勿寫進 Git 或 chat**）。
+
+## 正式 vs 開發 Instance（UF-2／D3／D4）
+
+| 情況 | 做法 |
+| --- | --- |
+| 第一次裝這個 `package` | `synopkgland deploy --host <nas>` |
+| 已裝**正式** Instance，要邊改邊玩、不影響使用者 | **`synopkgland deploy --host <nas> --dev`**（`{package}.dev`） |
+| NAS 上該 `package` 已是 **Curated**（App Package Attestation） | 預設 **`deploy` 會拒絕**（`CURATED_DEPLOY_REFUSED`）→ 建議 `--dev`；**不要**預設「取代商店版」 |
+| 必須用本機版覆蓋 Curated 正式版 | 僅在 NAS Administrator **明示危險確認**後：`--replace-curated`（證明降回 Local） |
+
+**規則**：若正式 Instance 已存在，skill **必須建議 `.dev`**，不得默默對同一 Package Identity 執行 `deploy`。
+
+## 命令
+
+```bash
+synopkgland deploy --host <nas>              # 正式 package
+synopkgland deploy --host <nas> --dev         # 開發 package（.dev）
+synopkgland deploy --host <nas> --replace-curated   # 危險：Curated 降級，需人確認
+
+synopkgland info --host <nas> [--dev]
+synopkgland log --host <nas> [--dev]
+synopkgland test --host <nas> [--dev]
+```
+
+成功後：DSM 按 Open；`info` 的 Open URL。已登入 DSM 不應再要平台密碼。
+
+## 未宣稱通過
+
+D3／D4／D12 實機與 15 分鐘黃金路徑仍可能失敗；失敗走 `diagnose.md`，不要宣稱產品已全綠。

package/skills/reference/diagnose.md

@@ -0,0 +1,42 @@
+# 排查（Diagnose）
+
+依 **穩定錯誤碼** 行動；權威是 `synopkgland validate` 輸出、`deploy`／Broker 回傳、`info`／`log` 的 readiness。不要猜 Compose。
+
+## validate／analyzer（修契約或 Compose）
+
+| 錯誤碼 | 下一步 |
+| --- | --- |
+| `CONTRACT_SCHEMA_INVALID`／`CONTRACT_MISSING_FIELD` | 對照 schema 與模板；補必填欄位，刪除非法鍵 |
+| `CONTRACT_SCHEMA_UNSUPPORTED` | `schema` 必須為整數 `1` |
+| `CONTRACT_INVALID_STRING`／`CONTRACT_ADMINPORT_INVALID` | 修正字串或 `adminport` 型別 |
+| `INSTALL_STRING_*`／`INSTALL_PARAMETER_UNREFERENCED` | 修正 install 預設值；在 compose 加 `${參數名}` |
+| `COMPOSE_MISSING` | 建立 `compose.yaml` |
+| `COMPOSE_PRIVILEGED_FORBIDDEN` 等安全碼 | 移除 privileged、host 網路、socket 掛載等 |
+| `COMPOSE_SERVICE_NOT_FOUND` | 修正 `adminport` 對應的 service |
+| `CONTRACT_ADMINPORT_UNMAPPED` | 在 compose 發布與 `adminport` 相同的 host port |
+
+流程：改檔 → `synopkgland validate` 直到通過。
+
+## deploy
+
+| 碼／訊息 | 下一步 |
+| --- | --- |
+| `VALIDATION_FAILED` | 先 `validate` |
+| `CURATED_DEPLOY_REFUSED` | 用 `--dev` 並行開發，或經管理員確認後 `--replace-curated` |
+| `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 上架 |
+
+## info／log／test --host
+
+| 觀察 | 下一步 |
+| --- | --- |
+| `NOT_INSTALLED`／log 說先 deploy | `deploy`（或 `--dev`） |
+| Readiness 非 RUNNING | `log --host` 看容器；Container Manager 深連結（勿假設使用者懂 Project） |
+| `test --host` Open smoke 失敗 | `info` 的 `openUrl`、registration port；identity 任務見 broker 日誌 |
+| Attestation 為 Curated 但要改本機 | 不要預設覆蓋；`--dev` 或顯式 `--replace-curated` |
+
+## 支援 bundle
+
+`synopkgland log --host` 結尾 diagnostics 已遮罩 secret；可複製給人類或 agent，**不要再貼 DSM 密碼**。

package/skills/reference/files.md

@@ -0,0 +1,37 @@
+# 檔案（Files）
+
+## 預設（私人 App）
+
+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。
+
+### 包現成 Compose
+
+- volume mapping 右側的 container target 與 `ro`／`rw` 是映像／upstream 的契約，保留原值；只把左側 host source 換成 `${NAME}`，並在 App Contract 宣告對應的 `shared_folder` 槽。
+- 原有 named volume 的 mount 與頂層 `volumes:` 宣告都保留。需要兩個既有 Share 就宣告兩個 `shared_folder` 槽；管理員在安裝時各選一個這台 NAS 的 Share。
+
+需要列出／讀寫這台 NAS 上登入者能看到的各個 Share 時，宣告 `files.*` 並走 File Gateway，不要掃 `/volume*`。
+
+`hello-web` **不**宣告廣域檔案 scope。`hello-files` 只宣告 Shared Folder。
+
+## 廣域 `files.read`／`files.write`／`files.delete`
+
+僅在使用者**明確要求**且理解風險時才加入；必須：
+
+1. 在 App Contract 明示（`integration`／權限模型依模板與 `validate`）。
+2. 用**人話**向 NAS Administrator 說明範圍（可讀寫哪些邏輯路徑、與 Shared Folder 的差異）。
+3. 取得同意後才 `deploy`；**不得**由模板或 skill 默默打開。
+
+安裝 wizard 會顯示同意文案；agent 在對話中也要用同樣語氣確認一次。
+
+## 開發
+
+```bash
+synopkgland dev --files-root <本機目錄>   # 可選：對應假檔案樹
+```
+
+## 下一步
+
+契約定案後 → `validate` → `deploy.md`

package/skills/reference/identity.md

@@ -0,0 +1,31 @@
+# 身分（Identity）
+
+Personal App 用 **broker-managed** 身分：已登入 DSM 的使用者 Open 時不再輸入另一組平台密碼。
+
+## 開發
+
+- `synopkgland dev` 啟動 mock Broker；`requireLogin` 等 API 與 NAS 同契約，但 User Context **不能**在 NAS 上使用。
+- 範例模板：`hello-web` 已含最小 Browser／Server SDK 整合。
+
+## 部署後驗證
+
+```bash
+synopkgland info --host <nas> [--dev]
+synopkgland test --host <nas> [--dev]
+```
+
+`info` 會顯示 attestation 種類、Open URL、readiness。
+
+## Package Identity 與 Instance
+
+- **正式**：`synology-app.yaml` 的 `package`（例如 `com.example.hello-web`）。
+- **開發用**：`{package}.dev`（`synopkgland deploy --dev`）；displayname 加「（開發中）」；不得進 Community Repository。
+
+若 NAS 上**已有正式 Instance**（Local 或 Curated），邊改邊玩應走 `.dev`，見 `deploy.md`。
+
+## 禁止
+
+- 不要把 DSM 密碼、session cookie、signing key 寫進 repo 或 chat。
+- 不要為了繞過登入而在 Compose 硬編碼長期 token。
+- 不要把 App 註冊成 Synology SSO Server 的 application；wrap 的 OIDC 只接 Broker facade（`oidc_compat`），見規格 identity §2.3。
+- 不要以為 OIDC 登入成功＝DSM 檔案 ACL。

package/skills/reference/wrap.md

@@ -0,0 +1,35 @@
+# 封裝（Wrap）
+
+已有 Compose 或要補齊 App Contract 時使用。權威仍是 schema + `validate`。
+
+## 命令
+
+```bash
+synopkgland inspect    # Compose 意圖、Web entry 提示
+synopkgland validate   # 契約 + Compose 安全與交叉引用
+```
+
+## 契約允許什麼（v1 schema 1）
+
+必填：`schema`、`package`、`version`、`displayname`、`description`、`maintainer`、`os_min_ver`。
+
+常見可選：`adminprotocol`、`adminport`、`adminurl`、`integration.web.launch`（`dsm-window` 預設｜`new-page`）、`install`（參數型別僅 `string`｜`boolean`｜`secret`｜`shared_folder`｜`dsm_user`）、`integration`、`permissions`。有 `shared_folder` 時必須有恰好一個 `dsm_user`，Compose 用 `${NAME_UID}:${NAME_GID}`，不要寫死 `0:0`。wrap 若只能 OIDC：`integration.identity.oidc_compat.redirect_path` 填 App 自己的 callback path，Compose 引用 `${SYNOPKGLAND_OIDC_ISSUER}`／`${SYNOPKGLAND_OIDC_CLIENT_ID}`，secret 讀檔 `SYNOPKGLAND_OIDC_CLIENT_SECRET`。**不要**在契約寫 issuer／domain／env 改名表。
+
+**禁止發明** schema 沒有的 top-level 鍵或 `install` 型別。`integration` 內容以模板與 `validate` 為準，不要自創 Broker DSL。
+
+## Compose 規則（analyzer 會擋）
+
+- 禁止：`privileged`、`network_mode: host`、裝置節點、`cap_add`、掛載 Docker socket。
+- `adminport` 必須對應到某 service 的 published TCP port。
+- `install` 參數須在 `compose.yaml` 以 `${NAME}` 引用。
+
+## 包現成 Compose 的掛載
+
+容器路徑跟映像／upstream 的 container target 走，原樣保留；只把 host source 換成 `${NAME}` 這類 install parameter。原有的 upstream named volume mount 與頂層 `volumes:` 宣告也保留，不要為了套模板改成 `/data`。需要既有 Share 時，管理員在安裝時選這台 NAS 的 Share。
+
+修復方式：看 `validate` 輸出的 `[錯誤碼]` 與「建議」行，對照 `diagnose.md`。**不要**為了過驗證而亂改 runtime 語意。
+
+## 下一步
+
+- 要身分／檔案整合 → `identity.md`／`files.md`
+- 要上 NAS → `deploy.md`

package/templates/compose-import/compose.yaml

@@ -0,0 +1,11 @@
+services:
+  app:
+    image: hello-world:latest
+    user: "${RUN_AS_UID}:${RUN_AS_GID}"
+    volumes:
+      - "${MEDIA_SHARE}:/media"
+      - "${BACKUP_SHARE}:/backup"
+      - "upstream_data:/var/lib/upstream"
+
+volumes:
+  upstream_data:

package/templates/compose-import/synology-app.yaml

@@ -0,0 +1,15 @@
+schema: 1
+package: com.synology.compose.import
+version: 0.1.0
+displayname: Compose Import
+description: Start from an existing Compose file and select two Shared Folders at install time.
+maintainer: Syno Package Land
+os_min_ver: "7.2-69057"
+
+install:
+  MEDIA_SHARE:
+    type: shared_folder
+  BACKUP_SHARE:
+    type: shared_folder
+  RUN_AS:
+    type: dsm_user

package/templates/hello-files/compose.yaml

@@ -0,0 +1,8 @@
+services:
+  worker:
+    image: alpine:3.20
+    command: ["sleep", "infinity"]
+    user: "${RUN_AS_UID}:${RUN_AS_GID}"
+    volumes:
+      - "${MEDIA_SHARE}/data:/data:ro"
+      - "${SYNOPKG_PKGVAR}/state:/state"

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

@@ -0,0 +1,13 @@
+schema: 1
+package: com.synology.hello.files
+version: 0.1.0
+displayname: Hello Files
+description: A minimal headless app with a Shared Folder mount.
+maintainer: Syno Package Land
+os_min_ver: "7.2-69057"
+
+install:
+  MEDIA_SHARE:
+    type: shared_folder
+  RUN_AS:
+    type: dsm_user

package/templates/hello-web/compose.yaml

@@ -0,0 +1,7 @@
+services:
+  web:
+    image: nginx:alpine
+    ports:
+      - "8080:80"
+    volumes:
+      - "${SYNOPKG_PKGVAR}/html:/usr/share/nginx/html:ro"

package/templates/hello-web/html/app.js

@@ -0,0 +1,23 @@
+import { createSynologyClient } from "./sdk.js";
+
+const status = document.getElementById("status");
+const userEl = document.getElementById("user");
+
+const client = createSynologyClient();
+
+try {
+  await client.auth.requireLogin();
+  const user = await client.auth.getCurrentUser();
+  if (status) {
+    status.textContent = "Signed in with DSM";
+  }
+  if (userEl) {
+    userEl.textContent = user.username;
+  }
+} catch (error) {
+  const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+  const message = error instanceof Error ? error.message : String(error);
+  if (status) {
+    status.textContent = code === "UNAUTHENTICATED" ? "DSM login required" : message;
+  }
+}

package/templates/hello-web/html/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Hello Web</title>
+  </head>
+  <body>
+    <h1>Hello Web</h1>
+    <p id="status">Opening with your DSM session…</p>
+    <p id="user"></p>
+    <script src="./bootstrap.js"></script>
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>

package/templates/hello-web/html/sdk.js

@@ -0,0 +1,68 @@
+export function createSynologyClient(options = {}) {
+  const bootstrap =
+    options.bootstrap ??
+    globalThis.__SYNOLOGY_BOOTSTRAP__ ??
+    (options.brokerBaseUrl
+      ? {
+          brokerBaseUrl: options.brokerBaseUrl,
+          jwksUrl: `${String(options.brokerBaseUrl).replace(/\/$/, "")}/.well-known/jwks.json`,
+          packageId: "com.synology.hello.web",
+        }
+      : undefined);
+  if (!bootstrap?.brokerBaseUrl) {
+    throw new Error("缺少 Platform SDK bootstrap。");
+  }
+  const apiBase = `${String(bootstrap.brokerBaseUrl).replace(/\/$/, "")}/api/v1`;
+  let accessToken = null;
+
+  async function parseJson(response) {
+    const text = await response.text();
+    const body = text ? JSON.parse(text) : {};
+    if (!response.ok) {
+      const error = body.error ?? {};
+      const err = new Error(error.message ?? `Broker request failed with status ${response.status}`);
+      err.code = error.code;
+      err.details = error.details;
+      throw err;
+    }
+    return body;
+  }
+
+  return {
+    auth: {
+      async requireLogin() {
+        const result = await parseJson(
+          await fetch(`${apiBase}/auth/login`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            credentials: "include",
+            body: JSON.stringify({ packageId: bootstrap.packageId }),
+          }),
+        );
+        accessToken = result.accessToken;
+        return result.user;
+      },
+      async getSession() {
+        if (!accessToken) {
+          return null;
+        }
+        const result = await parseJson(
+          await fetch(`${apiBase}/session`, {
+            headers: { authorization: `Bearer ${accessToken}` },
+            credentials: "include",
+          }),
+        );
+        return result.user;
+      },
+      async getCurrentUser() {
+        const session = await this.getSession();
+        if (!session) {
+          const err = new Error("尚未建立有效身份。");
+          err.code = "UNAUTHENTICATED";
+          throw err;
+        }
+        return session;
+      },
+    },
+  };
+}

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

@@ -0,0 +1,13 @@
+schema: 1
+package: com.synology.hello.web
+version: 0.1.0
+displayname: Hello Web
+description: A minimal Syno Package Land web app template.
+maintainer: Syno Package Land
+os_min_ver: "7.2-69057"
+adminprotocol: http
+adminport: 8080
+adminurl: /
+integration:
+  web:
+    launch: dsm-window

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

@@ -0,0 +1,7 @@
+services:
+  web:
+    image: nginx:alpine
+    ports:
+      - "8080:80"
+    volumes:
+      - "${SYNOPKG_PKGVAR}/html:/usr/share/nginx/html:ro"

package/templates/hello-web-page/html/app.js

@@ -0,0 +1,23 @@
+import { createSynologyClient } from "./sdk.js";
+
+const status = document.getElementById("status");
+const userEl = document.getElementById("user");
+
+const client = createSynologyClient();
+
+try {
+  await client.auth.requireLogin();
+  const user = await client.auth.getCurrentUser();
+  if (status) {
+    status.textContent = "Signed in with DSM";
+  }
+  if (userEl) {
+    userEl.textContent = user.username;
+  }
+} catch (error) {
+  const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+  const message = error instanceof Error ? error.message : String(error);
+  if (status) {
+    status.textContent = code === "UNAUTHENTICATED" ? "DSM login required" : message;
+  }
+}

package/templates/hello-web-page/html/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Hello Web Page</title>
+  </head>
+  <body>
+    <h1>Hello Web Page</h1>
+    <p id="status">Opening with your DSM session…</p>
+    <p id="user"></p>
+    <script src="./bootstrap.js"></script>
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>