@synopackageland/cli 0.13.1 → 0.15.0

package/schema/synopkgland-api-v1.schema.json

@@ -0,0 +1,423 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Syno Package Land API 描述 v1",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "format": {
+      "const": "synopkgland.api"
+    },
+    "version": {
+      "const": 1
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "package": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string",
+              "pattern": "^[A-Za-z][A-Za-z0-9_.+-]{0,127}$"
+            },
+            "version": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128
+            },
+            "displayName": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024
+            }
+          },
+          "required": [
+            "id",
+            "version",
+            "displayName"
+          ]
+        },
+        "aliases": {
+          "type": "array",
+          "uniqueItems": true,
+          "maxItems": 8,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-zA-Z][a-zA-Z0-9-]{0,63}$"
+          }
+        },
+        "provenance": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "developedBy": {
+              "enum": [
+                "synopkgland",
+                "third-party",
+                "unknown"
+              ]
+            },
+            "generator": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024
+            }
+          },
+          "required": [
+            "developedBy",
+            "generator"
+          ]
+        },
+        "entry": {
+          "enum": [
+            "policy",
+            "admin-only",
+            "app-privilege"
+          ]
+        },
+        "transport": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "path": {
+              "type": "string",
+              "pattern": "^/webman/3rdparty/[A-Za-z][A-Za-z0-9_.+-]{0,127}/cgi/api\\.cgi$"
+            },
+            "auth": {
+              "enum": [
+                "dsm-session",
+                "dsm-app-session"
+              ]
+            }
+          },
+          "required": [
+            "path",
+            "auth"
+          ]
+        },
+        "bindings": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 1024,
+          "propertyNames": {
+            "type": "string",
+            "maxLength": 128,
+            "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "effect": {
+                "enum": [
+                  "read",
+                  "write",
+                  "destructive"
+                ]
+              },
+              "permission": {
+                "enum": [
+                  "public",
+                  "authenticated",
+                  "administrators"
+                ]
+              }
+            },
+            "required": [
+              "effect",
+              "permission"
+            ]
+          }
+        },
+        "commands": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 1024,
+          "propertyNames": {
+            "type": "string",
+            "maxLength": 128,
+            "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "summary": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 1024
+              },
+              "cli": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 8,
+                "items": {
+                  "type": "string",
+                  "maxLength": 64,
+                  "pattern": "^[a-z][a-z0-9-]*$"
+                }
+              },
+              "effect": {
+                "enum": [
+                  "read",
+                  "write",
+                  "destructive"
+                ]
+              },
+              "permission": {
+                "enum": [
+                  "public",
+                  "authenticated",
+                  "administrators"
+                ]
+              },
+              "paramsSchema": {
+                "type": "object"
+              },
+              "resultSchema": {
+                "type": "object"
+              },
+              "examples": {
+                "type": "array",
+                "maxItems": 16,
+                "items": {
+                  "type": "object"
+                }
+              },
+              "flow": {
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "type": {
+                        "const": "invoke"
+                      },
+                      "method": {
+                        "type": "string",
+                        "maxLength": 128,
+                        "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "method"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "type": {
+                        "const": "ndjson"
+                      },
+                      "method": {
+                        "type": "string",
+                        "maxLength": 128,
+                        "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "method"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "type": {
+                        "const": "upload"
+                      },
+                      "method": {
+                        "type": "string",
+                        "maxLength": 128,
+                        "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+                      },
+                      "fileParam": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                      },
+                      "parentParam": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                      },
+                      "nameParam": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "method",
+                      "fileParam",
+                      "parentParam",
+                      "nameParam"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "type": {
+                        "const": "paginate"
+                      },
+                      "method": {
+                        "type": "string",
+                        "maxLength": 128,
+                        "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+                      },
+                      "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                      },
+                      "offsetParam": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                      },
+                      "limitParam": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                      },
+                      "pageSize": {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 1000
+                      },
+                      "maxPages": {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 1000
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "method",
+                      "items",
+                      "offsetParam",
+                      "limitParam",
+                      "pageSize",
+                      "maxPages"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "type": {
+                        "const": "job"
+                      },
+                      "start": {
+                        "type": "string",
+                        "maxLength": 128,
+                        "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+                      },
+                      "poll": {
+                        "type": "string",
+                        "maxLength": 128,
+                        "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+                      },
+                      "result": {
+                        "type": "string",
+                        "maxLength": 128,
+                        "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+                      },
+                      "jobId": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                      },
+                      "idParam": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                      },
+                      "state": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024
+                      },
+                      "done": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 1024
+                        }
+                      },
+                      "failed": {
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 1024
+                        }
+                      },
+                      "intervalMs": {
+                        "type": "integer",
+                        "minimum": 10,
+                        "maximum": 60000
+                      },
+                      "timeoutMs": {
+                        "type": "integer",
+                        "minimum": 10,
+                        "maximum": 3600000
+                      }
+                    },
+                    "required": [
+                      "type",
+                      "start",
+                      "poll",
+                      "jobId",
+                      "idParam",
+                      "state",
+                      "done",
+                      "failed",
+                      "intervalMs",
+                      "timeoutMs"
+                    ]
+                  }
+                ]
+              }
+            },
+            "required": [
+              "summary",
+              "cli",
+              "effect",
+              "permission",
+              "flow"
+            ]
+          }
+        }
+      },
+      "required": [
+        "package",
+        "aliases",
+        "provenance",
+        "entry",
+        "transport",
+        "bindings",
+        "commands"
+      ]
+    },
+    "sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    }
+  },
+  "required": [
+    "format",
+    "version",
+    "payload",
+    "sha256"
+  ]
+}

package/skills/SKILL.md

@@ -7,7 +7,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 依已實作能力區分 DSM session 檔案、私有 jobs 與 App 登入；delegate 已實作並隨 CLI 提供固定操作的離線委託（預設 `files.moveFromStaging`）；共用 delegate／rootOps executor 的完整裝置生命週期驗收仍待完成，不得宣稱已通過；支援邊界依 delegate guide／support matrix，禁止發明新的身分平台。
 
-Start with `synopkgland init -t native-go`, `synopkgland init -t binary`, or `synopkgland init -t compose`. Read reference/create.md or reference/wrap.md, then reference/deploy.md. Native CGI session checks belong to the package. For wrapping upstream OSS with DSM accounts, read [reference/identity-gateway.md](reference/identity-gateway.md) first. It covers native and host-network Compose upstreams, mode selection, isolation, account deletion and verification. Fixed package credentials govern container data access.
+Start with `synopkgland init -t native-go`, `synopkgland init -t binary`, or `synopkgland init -t compose`. Read reference/create.md or reference/wrap.md, then reference/deploy.md. Native CGI session checks belong to the package. For wrapping upstream OSS with DSM accounts, read [reference/identity-gateway.md](reference/identity-gateway.md) first. For all Compose work, read [reference/compose.md](reference/compose.md): schema-2 upstream files, generated override, SDK planner, fixed package identity and current DSM blockers. Containers do not inherit a signed-in user's File Station ACL. Existing Shared Folder mounts are blocked until official protected ACL/project control is verified.
 
 Never install, uninstall, publish or modify NAS data without task authorization. Prefer check, inspect and deploy --dry-run for reviewable artifacts.
 
@@ -131,3 +131,36 @@ sweep forward the cancel instead of admitting it.
   adapt a real producer; show Saved only from a protected committed receipt.
 - Wizard support is measured on vt-nas DSM 7.4 via a session-only SSH local
   forward. This is not proof of other DSM releases or full writer/reboot behavior.
+
+## 開啟方式
+
+原生 App 在 `dsm-package.yaml` 設定 `ui.launch: dsm-window | new-page`。
+SDK 原生 App 的內建預設為 `dsm-window`。使用 `@synopackageland/ui` 的前端維持視窗；
+其他前端必須明確設定 `new-page`，不宣告 Application Portal。
+Scaffold 明確寫入此選擇，plain／binary 使用 `new-page`，Vue UI SDK 使用
+預設的 `dsm-window`（省略 `ui.launch`）。原生 manifest 省略 `ui.launch` 時解析為 `dsm-window`，CLI 不猜測前端依賴。
+
+`new-page` 產生 DSM `type: "standalone"` launcher，主選單及套件中心皆在 DSM
+本身的 origin 開啟全頁。`ctx.fullPage`、`ctx.appIcon`、SynoToken／session、
+`ctx.launchParams`／`onLaunch`、`entry` 權限沿用共用 wrapper；全頁的標題、
+favicon 與手機 viewport 由 wrapper 設定。不需要 `pureEnv` 或 `allowAltPort`。
+
+Application Portal 是獨立 opt-in：不想要別名就省略 `portal`，不生成
+`defaultAlias`、Portal 面板／capability 或 Web Station alias；沒有 Portal
+不是 inspect／info／doctor 問題。明確啟用 `portal` 時才將其 alias 作為 `defaultAlias`。
+
+Docker／web service App 設定 `integration.web.launch`，內建預設是 `new-page`；
+省略開啟方式時直接開新分頁，不宣告 Application Portal。SDK 原生 App
+省略時使用 `dsm-window`；非 UI SDK 原生 App 必須明確寫 `ui.launch: new-page`。
+Web service 主選單使用
+`type: "url"` 與明確的 `url` 指向既有 DSM gateway。明確 `access: public` 才保留 Web Station
+alias；這是服務入口，不是 SDK Application Portal。DSM 會將 standalone URL 改寫成 launchApp 頁面，
+需要 AppInstance／AppWindow JS class；schema 1 web service 沒有該 class，因此使用 url。需要 DSM 視窗時明寫 `dsm-window`。
+
+Schema 2 的 `dsm-package.yaml` + `identity_gateway` + `compose` 同樣視為
+web service：省略 `ui.launch` 時預設 `new-page`，使用 standalone launcher，
+不帶 Application Portal。兩條 Compose 路線共用 `contract/app-launch.ts`
+解析開啟方式與選擇 launcher 型別；明確的 `ui.launch` 可覆寫預設。
+只有沒有 web service 的 SDK 原生 App 省略時才預設 `dsm-window`。
+
+For controlling installed Apps or designing task-level AI commands, read [reference/ctl.md](reference/ctl.md). Use ctl host list, register/renew explicitly, discover all commands, and always name the host when agents may operate multiple NAS machines.