@synopackageland/cli 0.32.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {

package/schema/package-metadata.schema.json

@@ -98,9 +98,38 @@
       }
     },
     "upstream": {
-      "type": "string",
-      "maxLength": 2048,
-      "pattern": "^https?://"
+      "oneOf": [
+        {
+          "type": "string",
+          "maxLength": 2048,
+          "pattern": "^https://"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "name",
+            "url"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 80
+            },
+            "url": {
+              "type": "string",
+              "maxLength": 2048,
+              "pattern": "^https://"
+            },
+            "license": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 80
+            }
+          }
+        }
+      ]
     }
   }
 }

package/schema/synology-app.schema.json

@@ -189,9 +189,38 @@
       "additionalProperties": false,
       "properties": {
         "upstream": {
-          "type": "string",
-          "maxLength": 2048,
-          "pattern": "^https?://"
+          "oneOf": [
+            {
+              "type": "string",
+              "maxLength": 2048,
+              "pattern": "^https://"
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "name",
+                "url"
+              ],
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 80
+                },
+                "url": {
+                  "type": "string",
+                  "maxLength": 2048,
+                  "pattern": "^https://"
+                },
+                "license": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 80
+                }
+              }
+            }
+          ]
         },
         "changelog": {
           "oneOf": [

package/skills/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-CLI 0.32.0 installs templates through `~0.31.0`. A templates patch needs only a
+CLI 0.32.1 installs templates through `~0.31.0`. A templates patch needs only a
 templates release; npm install/update selects a patch in that minor line. The CLI
 uses the locally installed templates and reads their SDK pin for defaults; it
 never downloads templates at runtime. Preserve the lockfile and use `npm ci` for
@@ -48,6 +48,8 @@ Buttons follow DSM's policy ([reference/ui-vue.md](reference/ui-vue.md#buttons),
 
 Read [reference/ui-json.md](reference/ui-json.md) when generating or editing JSON UI; discover the installed catalog, validate the spec, then render and fix layout issues.
 
+Read [reference/host-install.md](reference/host-install.md) before NAS authentication, store/local-SPK installation or package removal. All DSM commands share the registered host session.
+
 ## UI copywriting
 
 For UI/locale strings we author in the SDK, UI package, templates and our own

package/skills/reference/compose.md

@@ -247,7 +247,7 @@ declared availability readiness, LAN isolation/egress, protected grant lifecycle
 ACLs, two-user visibility and clean install/upgrade/reboot/stop/uninstall before
 calling the package supported on a NAS. No NAS is accessed by the build gate.
 
-The unified Compose contract uses SDK defaults from locally installed templates `~0.31.0` with CLI 0.32.0. Templates patches can ship independently; npm install/update resolves them, and SDK defaults come from the installed templates. SDK minor upgrades do not require a CLI release when they declare supported executor manifest format 1; the resolved SDK owns the release mapping and verified payload digests. The CLI does not fetch templates at runtime. The legacy packaging route and bridge publish mode are removed.
+The unified Compose contract uses SDK defaults from locally installed templates `~0.31.0` with CLI 0.32.1. Templates patches can ship independently; npm install/update resolves them, and SDK defaults come from the installed templates. SDK minor upgrades do not require a CLI release when they declare supported executor manifest format 1; the resolved SDK owns the release mapping and verified payload digests. The CLI does not fetch templates at runtime. The legacy packaging route and bridge publish mode are removed.
 
 Primary override files, and each included override set, must share a directory. Cross-directory override bases are rejected before loader I/O. Included implicit .env files are confined, inventoried and preserved; symlinks are rejected.
 

package/skills/reference/ctl.md

@@ -2,15 +2,15 @@
 
 Use this for operating installed Apps, rather than building/deploying projects.
 
-1. `synopkgland ctl host list --json` checks registered machines and sessions.
-2. Register with `ctl host add nas --url https://nas.example:5001 --username alice`, or renew with `ctl host login nas`. Credentials are hidden interactive input; `--password-stdin` is available. Do not put passwords/OTP in argv. Sessions and remembered-device tokens use OS secure storage, never a plaintext fallback.
+1. `synopkgland host list --json` checks registered machines and sessions.
+2. Register with `host add nas --url https://nas.example:5001 --username alice`, or renew with `host login nas`. Credentials are hidden interactive input; `--password-stdin` is available. Do not put passwords/OTP in argv. Sessions and remembered-device tokens use OS secure storage, never a plaintext fallback.
 3. Run `synopkgland ctl list --host nas --json` for all registered Apps, commands, schemas, effects, permissions and executable examples. If description access needs approval, ask the user to approve the whole candidate batch; do not self-approve. An explicit `--approve-installed` records permission to send the DSM session to the displayed inventory's fixed description endpoints. Use `--app <package>` to narrow the batch. No description endpoint is anonymous.
 4. Use the discovered alias, CLI path and typed flags with an explicit `--host nas`; inspect `--help` and `--dry-run` before execution. For example, `synopkgland ctl notes list --status pending --host nas --dry-run`. Use the real command/schema from discovery, not this illustrative name.
 5. Reads need no write confirmation. For authorized write/destructive commands, add `--yes`; without it the CLI returns a plan and confirmation error. A --yes flag does not replace the user's authorization or the App's backend checks.
 
-There is no shared current context: with multiple hosts, always specify --host. `--host a,b` and --all-hosts return per-host results, with exit 8 on partial failure. Do not retry a write merely because one host failed; query its state first. --refresh rereads descriptions; unchanged package versions use the host/account/package/version/hash cache. Never assume cached metadata grants resource permission.
+With multiple hosts, select a default with `synopkgland host default <name>` or specify --host. `--host a,b` and --all-hosts return per-host results, with exit 8 on partial failure. Do not retry a write merely because one host failed; query its state first. --refresh rereads descriptions; unchanged package versions use the host/account/package/version/hash cache. Never assume cached metadata grants resource permission.
 
-Use `ctl host show nas` to inspect approvals/pins, `ctl host revoke nas PackageID` to remove an App approval, `ctl host logout nas` to retain registration, and `ctl host remove nas --yes` to delete sessions, device token, approvals and cache. A failed NAS logout is reported independently from successful local removal.
+Use `host show nas` to inspect approvals/pins, `host revoke nas PackageID` to remove an App approval, `host logout nas` to retain registration, and `host remove nas --yes` to delete sessions, device token, approvals and cache. A failed NAS logout is reported independently from successful local removal.
 
 Stdout defaults to JSON without a TTY. Success is {ok:true,data}; failure is {ok:false,error:{code,message,hint,allowed?}}. Multi-host output uses {ok,results:[{host,ok,data|error}]}. Follow the concrete hint and complete allowed list; do not guess another method or bypass ctl with raw HTTP. Exit codes: 2 authentication, 3 parameters/names, 4 permissions/trust, 5 App/contract, 6 network, 7 confirmation, 8 partial failure.
 

package/skills/reference/deploy.md

@@ -1,3 +1,5 @@
+Before deployment, register a NAS with `synopkgland host add nas --url https://nas.example:5001`, then renew it with `synopkgland host login nas`. See [host-install.md](host-install.md) for shared sessions, automation, install and uninstall.
+
 # Build and deploy
 
 1. Run `synopkgland check` and `synopkgland build --arch x86_64` (use aarch64 or armv7 for those targets; armv7 must be listed in `arches`; its jobs, daemon and executor are built but not NAS-verified). deploy detects the NAS arch, except on Marvell CPUs, where it asks for `--arch`.

package/skills/reference/host-install.md

@@ -0,0 +1,55 @@
+# Shared NAS login and package installation
+
+Register once with `synopkgland host add nas --url https://nas.example:5001 --username alice`.
+The CLI prompts for the password and OTP when DSM requires it. Session cookies,
+SynoToken and remembered-device tokens stay in the OS credential store; host
+metadata and App approvals stay under `~/.synopkgland/ctl`. Passwords are not saved.
+Use `--ca <PEM>` when adding a host with a private CA. Certificate verification stays on.
+
+Use `synopkgland host login nas` to renew an expired session. `host list`,
+`host show nas`, `host logout nas`, `host remove nas --yes` and
+`host revoke nas <package-id>` manage the registration, login and App approvals.
+`host default nas` selects a default; with one host it is selected automatically.
+Every DSM command accepts `--host nas`, including ctl, deploy, status, logs,
+install and uninstall. ctl still requires explicit App description approval.
+
+For authorized package changes:
+
+```sh
+synopkgland install SynoReclaim --host nas --dry-run --json
+synopkgland install SynoReclaim --host nas --yes --json
+synopkgland install SynoReclaim@0.1.1-1591 --host nas --yes
+synopkgland install ./MyApp.spk --host nas --param NAME=value --yes
+synopkgland status SynoReclaim --host nas --json
+synopkgland uninstall SynoReclaim --host nas --yes --json
+```
+
+Store installs default to `https://packages.synopkgland.com`; `--source <HTTPS URL>`
+selects another source. The source is queried for the NAS platform and DSM build.
+The CLI plans dependencies from the same feed, reports missing Synology packages,
+checks every feed size/MD5/SHA-256 pin and inspects SPKs before uploading.
+`<package-id>@version` selects an exact available release; downgrades are refused.
+`--dry-run` reads NAS/source metadata and prints the plan without uploading or changing DSM.
+Local SPKs pass the same inspect, architecture and DSM checks before installation.
+The inspection reports signature presence; it does not cryptographically authenticate a publisher.
+Install wizard values use repeated `--param NAME=value`; values are private and
+not printed in plans. DSM package hooks validate their meaning. Install/removal
+require administrator rights. Uninstall hooks can remove package data; review the App's policy.
+A failed multi-package install may leave earlier dependencies installed; inspect status before retrying.
+
+For automation, provide `DSM_USERNAME` and `DSM_PASSWORD` in the process environment
+(and `DSM_OTP` if required), with a registered `--host` using that same account.
+These values create an in-memory session and are never written to disk. Without a
+registration, install/deploy/status/logs also accept `DSM_URL` with both credentials.
+Use an HTTPS URL and a trusted certificate. Supply secrets through your CI secret
+store, never literal command arguments, committed files or command output.
+`host add/login --password-stdin` supports a password from standard input.
+
+Default NAS HTTPS certificates work through trust on first use: before sending a
+password, the CLI pins an untrusted leaf certificate's SHA-256 and prints
+`Trusting the NAS certificate <short fingerprint> (self-signed)`. Subsequent
+requests check the exact leaf. `HOST_CERT_CHANGED` shows old/new fingerprints;
+verify them with the user, then use `synopkgland host trust <name>` only after
+confirmation. Never disable TLS checks. `host add --fingerprint <sha256>` pins an
+expected leaf; `--ca <PEM>` uses a CA instead. Network errors distinguish
+HOST_TLS_UNTRUSTED, HOST_DNS_FAILED, HOST_CONNECTION_REFUSED and HOST_TIMEOUT.

package/skills/reference/upstream-fork.md

@@ -27,7 +27,8 @@ Pass `--upstream <repo-url>` (or retain the `upstream` Git remote), your verifie
 GitHub owner profile with a bounded lookup, using its display name then login.
 Offline or unsupported hosts leave an explicit maintainer TODO. Missing publisher
 configuration leaves a distributor TODO. Resolve these manually before release.
-`metadata.upstream` records the repository; `check` warns, without failing, for
+`metadata.upstream: {name, url}` records the original project name and HTTPS repository;
+URL shorthand is normalized to that object in SPK metadata; `check` warns, without failing, for
 missing attribution or a maintainer that equals the distributor. The fork layout
 also enables this warning without `metadata.upstream`.