@synopackageland/cli 0.15.4 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.17.0 (2026-10-19)
+
+- Pin SDK/App 0.17.0 and templates 0.17.1, with UI 0.12.1 in Vue scaffolds; package the executor fixes for directory users and request batches.
+- Fetch SynoToken early in standalone and Portal windows so the first API request can start sooner.
+- Allow Portal without an executor from DSM 7.2-64570. Request DSM nginx reload through INFO during install, upgrade and uninstall; DSM 7.1 still needs an executor for registration.
+
+- Expose ctx.batch in generated SDK windows, sharing the existing request guards and token recovery. Keep single-call retries unchanged; never replay a batch after partial execution.
+
+## 0.16.0 (2026-10-19)
+
+- Pin SDK/templates 0.16.0; generated Shared Folder flows use the shared SDK readback and settings components.
+- Add the upstream-fork recipe/init/check workflow, Container Manager preflight and architecture-matched storage initializer packaging while preserving official images.
+- Remove internal deployment details from published content and scan actual npm tarballs before release.
+
 ## 0.15.4 (2026-10-18)
 
 - Fix Compose import and undeclared SDK defaults after CLI-only patch releases. Resolve the SDK from the exactly pinned templates' Go module instead of assuming the CLI and SDK share a patch version; daemon-control defaults use the same source.
@@ -174,8 +188,8 @@ only its protocol README's wording, and nothing in the CLI depends on it.
 
 - `ctx.call` rejects `APP_STOPPED` at once: a stopped package waits for the
   user to start it in Package Center, so the SDK's stopped copy shows within a
-  page's next read instead of 30 s later (Download Hub 29.3 s, t-0527; Reclaim
-  showed its old content or loading, t-0528). `APP_STARTING` and
+  page's next read instead of 30 s later (Download Hub 29.3 s; Reclaim
+  showed its old content or loading). `APP_STARTING` and
   `EXECUTOR_STARTING` repeat for 4 s of waiting (0.5, 1, 2, 0.5 s), so a short
   start still shows the page nothing and the SDK's starting copy follows a
   longer one within its own 4 s recheck. `executor.control`, which the window's
@@ -225,7 +239,7 @@ e2e 新增 `openUntilLoaded`（`signIn` 遇 `net::ERR_ABORTED` 最多重開約 3
   the newest one it read (`lastStatus()`); a `status()` asked for while a read
   runs shares it. The SDK's `PortalSettings` starts from it, so a settings
   page no longer moves when its placeholder rows become the real section
-  (Reclaim: 100 px, t-0520).
+  (Reclaim: 100 px).
 
 ## 0.10.6 (2026-10-15)
 
@@ -244,7 +258,7 @@ digest 與 0.10.5 相同；SDK 下限維持 0.10.5。e2e 新增 `openPath`、`ha
 
 - `signIn`, `openDesktop` and `openPortal` open their page once more when
   the first navigation fails with `net::ERR_ABORTED`, which about one run in
-  ten met as DSM's desktop navigated on its own (t-0499, t-0500); any other
+  ten met as DSM's desktop navigated on its own; any other
   failure, or a second abort, still fails. The helper is exported as
   `openPath(app, path)`.
 - The DSM window's `status()` answers a pinned executor that reports
@@ -330,7 +344,7 @@ digest 與 0.10.4 相同；新增 `@synopackageland/cli/e2e`。
   `authorization.status`, `executor.status`) while the package is stopped or
   starting: they reject with the code at once, and SDK 0.10.5's panels show the
   stopped or starting package and check again on their own. A page no longer
-  shows nothing for the first seconds after an upgrade (6.7 s in t-0503). Calls
+  shows nothing for the first seconds after an upgrade (6.7 s in the regression test). Calls
   that change something, approvals and controls among them, still repeat for up
   to 30 s. `ctx.executor.status()` for a user who is not an administrator says
   the package is stopped or starting instead of `admin_required`.
@@ -362,12 +376,12 @@ before its timeout.
 - The window approval of an upgrade (outdated tasks) makes 11 scheduler calls
   instead of 12: the outdated boot task is deleted by the approval's own first
   EventScheduler get, made moments before the password, instead of a second
-  get (2.9 s on the test NAS in t-0484). The control task is still read again by id
+  get (2.9 s on the test NAS in the regression test). The control task is still read again by id
   before its delete (spec/scheduler/v1). A fresh approval stays at 8.
   繁中：升級核准的排程呼叫由 12 降為 11（boot 任務不再於刪除前重讀）。
 - A scope approval reads the executor's selection back every second at most
   (it backed off to 2 s), so the window sees the landed scope within a second
-  of `scope.confirm` (the Dialog closed 4.8 s after it in t-0482). Removing
+  of `scope.confirm` (the Dialog closed 4.8 s after it in the regression test). Removing
   the temporary selection task still lists Task Scheduler first, as
   spec/scheduler/v1 requires of a delete.
   繁中：範圍核准讀回間隔上限 2 s → 1 s，confirmed 後 1 s 內看到結果。
@@ -376,7 +390,7 @@ before its timeout.
   before any request: the pinned, running executor reads `ready`; anything
   else stays `blocked` with `admin_required`. Task Scheduler is still read only
   for administrators. A user no longer sees an approved executor as waiting
-  for approval (t-0482 F7).
+  for approval.
   繁中：非管理員的 `ctx.executor.status()` 會向 App 的 `executor.status` 詢問，已核准且
   執行中即為 `ready`，不再一律回 `admin_required`。
 

package/README.md

@@ -95,7 +95,7 @@ Add them with `init --with …` or later with `synopkgland add <capability…>`.
 | `login` | Sign users in with their DSM account, without the DSM desktop | Nobody; requires HTTPS for password sign-in |
 | `delegate` | Move files into a user's chosen folder while the user is offline | An administrator, once |
 | `root-ops` | Run fixed `root/*.sh` scripts for administrators | An administrator, once |
-| `portal` | Open the app from its own Application Portal alias, with a login page style (`login_style` changes the colour, wallpaper and title) | An administrator sets the alias; needs `root-ops` or `delegate` and DSM 7.1-42661+ (below 7.2-64570 the executor registers the entry) |
+| `portal` | Open the app from its own Application Portal alias, with a login page style (`login_style` changes the colour, wallpaper and title) | An administrator applies the alias; DSM 7.2-64570+ needs no executor (INFO asks DSM to reload nginx on uninstall). DSM 7.1-42661+ needs an executor to register the entry |
 
 Delegate is implemented; its default operation is `files.moveFromStaging`.
 Device lifecycle acceptance on real hardware is still pending for delegate and root operations.
@@ -311,3 +311,10 @@ Read `synopkgland skill show ctl` for the AI workflow, batch discovery approval,
 cache refresh, host removal/revocation and explicit `ctl.commands` authoring.
 API descriptions are private SPK files named `synopkgland-api.json`, served
 only by the authenticated fixed `synopkgland.describe` CGI operation.
+
+Generated SDK windows expose `ctx.batch([{method, params}, ...])` when the
+selected SDK supplies its batch factory. One to eight independent JSON reads
+share a request; results keep input order and retain per-method errors. A batch
+uses the same token recovery, request deadline and cancellation as `ctx.call`,
+and is never replayed automatically. Older SDKs and binary backends retain the
+single-call client. Rebuild the window with the current CLI/SDK to adopt it.

package/assets/init-compose.md

@@ -0,0 +1,33 @@
+# Compose App development
+
+Run `synopkgland skill list`, then `synopkgland skill show orchestrator`,
+`synopkgland skill show compose` and `synopkgland skill show upstream-fork`.
+Prefer `check --json`, `build --json`, `inspect <spk> --json` for reviewable results.
+
+Never write `AppPortal.json` or `@appconf` directly, or relay QuickConnect.
+Compose has no native Application Portal alias; use its supported web entry.
+
+Use dsm-package.yaml schema 2. Keep upstream Compose bytes unchanged; declare DSM
+policy in compose.files and compose.web. Never use file/targets/address_env or
+identity_gateway.upstream: the SDK planner derives ingress.
+
+## Compose health and launch
+
+Select compose.web.health.path and its actual expected 2xx status before
+check/build. Redirects are not followed; a 302 to login is unhealthy. check is
+static, not an HTTP or arbitrary-UID/storage probe. Test the selected official image as
+the package UID, including writable volumes, first setup and upgrade.
+Omitted ui.launch means new-page via the SDK standalone launcher, without
+Application Portal. Headless Apps omit compose.web and have no launcher.
+Compose ctl is unsupported.
+
+Use supported upstream config files, environment, argv or reverse proxy for
+login/settings. For integrated upstream Apps, select supported trusted-header authentication or disable upstream login behind the DSM admin gate; or use the existing SDK 0.17.0 token adapter: OpenList uses mode: token, access: dsm-admins and entry: admin-only. Its unmodified admin token CLI supplies a package-private 0600 credential; the gateway injects Authorization server-side after DSM admission, without delivering it to the browser. All DSM admins share one upstream admin; token reset requires package restart; WebDAV keeps its own credentials. Verify each App adapter and DSM admission separately.
+Containers use the package account and a dedicated bridge; they do not inherit
+an interactive user's NAS ACL. Do not use root/chown during any App lifecycle
+phase. Preserve licenses and dependency/source provenance. Read the CLI skill
+reference/compose.md and reference/upstream-fork.md for the full recipe.
+
+Public npm access does not grant anonymous Go SDK access. Obtain authorised
+source/cache access or a matching SYNOPKGLAND_SDK_DIR checkout first. Never copy
+credentials into the App. Do not install, publish or modify NAS data without task authorization.

package/assets/init-upstream/build-source.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# Native App payload hook. SPL_UPSTREAM_SOURCE is the merged fork root.
+# Stage official release binaries only after verifying pinned SHA-256 values
+# (the OpenList route), or compile the merged source with a source build hook.
+# Stage daemon.targets under synology/; pin toolchains/dependencies for builds.
+# Keep upstream source unchanged.
+# Every App lifecycle phase uses the package UID. Do not add root/chown hooks.
+echo 'SOURCE_BUILD_REQUIRED: implement the native synology/build-source.sh.' >&2
+exit 2

package/assets/init-upstream/update-image.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Use the CLI's existing OCI registry resolver; never build or publish an image.
+import {mkdtempSync, readFileSync, writeFileSync, rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {spawnSync} from 'node:child_process';
+const [tag] = process.argv.slice(2);
+const match = /^v?((?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*))$/.exec(tag ?? '');
+if (!match) throw new Error('Use the selected stable upstream tag.');
+const config = JSON.parse(readFileSync(new URL('./upstream-recipe.json', import.meta.url), 'utf8'));
+if (config.kind !== 'official-image' || !['tag', 'version'].includes(config.imageTag)) throw new Error('Invalid official image recipe.');
+const imageTag = config.imageTag === 'version' ? match[1] : tag;
+const reference = `${config.repository}:${imageTag}`;
+const temp = mkdtempSync(join(tmpdir(), 'synopkgland-image-pin-'));
+try {
+  // images pin edits only compose.yaml; use a bounded temporary project so the
+  // App's base Compose and upstream source remain unchanged on lookup failure.
+  writeFileSync(join(temp, 'dsm-package.yaml'), 'schema: 2\n');
+  writeFileSync(join(temp, 'compose.yaml'), JSON.stringify({services: {[config.service]: {image: reference}}}, null, 2) + '\n');
+  const result = spawnSync('synopkgland', ['--project', temp, 'images', 'pin'], {stdio: 'inherit'});
+  if (result.error || result.status !== 0) throw new Error('Official image digest lookup failed; no Compose override was changed.');
+  const pinned = JSON.parse(readFileSync(join(temp, 'compose.yaml'), 'utf8'));
+  const image = pinned.services[config.service].image;
+  if (!image.startsWith(`${reference}@sha256:`) || !/@sha256:[0-9a-f]{64}$/.test(image)) throw new Error('Registry lookup did not produce the selected tag plus digest.');
+  writeFileSync(new URL('./compose.image.yaml', import.meta.url), JSON.stringify(pinned, null, 2) + '\n');
+} finally {rmSync(temp, {recursive: true, force: true});}

package/assets/init-upstream/upgrade.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# One explicit stable tag; no latest guessing, push, image publication or NAS access.
+set -euo pipefail
+packaging=$(cd -- "$(dirname -- "$0")" && pwd)
+repo=$(cd -- "$packaging/.." && pwd)
+cd "$repo"
+[[ $# == 2 && $1 =~ ^v?(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]] || {
+  echo 'Usage: bash synology/upgrade.sh <[v]X.Y.Z> <increasing-build-number>' >&2; exit 2;
+}
+[[ $(git rev-parse --show-toplevel) == "$repo" ]] || { echo 'Run inside a source fork.' >&2; exit 2; }
+[[ -z $(git status --porcelain --untracked-files=normal) ]] || { echo 'Commit changes before upgrading.' >&2; exit 2; }
+git remote get-url upstream >/dev/null
+node "$packaging/version.mjs" "$1" "$2" --validate
+# Fetch the named remote tag into a private ref: a local tag can never substitute for it.
+git fetch --no-tags upstream "+refs/tags/$1:refs/synopkgland/selected-upstream"
+commit=$(git rev-parse 'refs/synopkgland/selected-upstream^{commit}')
+[[ -z $(git ls-tree "$commit" -- synology) ]] || { echo 'Upstream owns synology/; choose another integration layout.' >&2; exit 2; }
+previous=$(git describe --tags --abbrev=0 --match '[0-9]*' --match 'v[0-9]*' HEAD 2>/dev/null || true)
+if [[ -f "$packaging/upstream-source.json" ]]; then
+  previous=$(node -e 'process.stdout.write(JSON.parse(require("fs").readFileSync(process.argv[1])).commit)' "$packaging/upstream-source.json")
+fi
+if [[ -n $previous ]]; then
+  git merge-base --is-ancestor "$previous" "$commit" || { echo 'Refusing upstream downgrade/divergent history.' >&2; exit 2; }
+  [[ -z $(git diff "$previous" HEAD -- . ':(exclude)synology') ]] || { echo 'Wrapper changed upstream files outside synology/.' >&2; exit 2; }
+else
+  # First adoption must already be based on the selected source tag.
+  git merge-base --is-ancestor "$commit" HEAD
+  [[ -z $(git diff "$commit" HEAD -- . ':(exclude)synology') ]] || { echo 'Initial fork must preserve upstream source.' >&2; exit 2; }
+fi
+git merge --no-ff --no-edit "$commit"
+[[ -z $(git diff "$commit" HEAD -- . ':(exclude)synology') ]] || { echo 'Upstream files differ after merge; resolve before building.' >&2; exit 2; }
+kind=$(node -e 'process.stdout.write(JSON.parse(require("fs").readFileSync(process.argv[1])).kind)' "$packaging/upstream-recipe.json")
+if [[ $kind == official-image ]]; then
+  node "$packaging/update-image.mjs" "$1"
+elif [[ $kind != native-source ]]; then
+  echo 'Unknown upstream recipe kind.' >&2; exit 2
+fi
+node "$packaging/version.mjs" "$1" "$2"
+node -e 'const fs=require("fs");fs.writeFileSync(process.argv[1],JSON.stringify({tag:process.argv[2],commit:process.argv[3],build:Number(process.argv[4])},null,2)+"\n")' "$packaging/upstream-source.json" "$1" "$commit" "$2"
+export SPL_UPSTREAM_SOURCE="$repo"
+export SPL_UPSTREAM_TAG="$1"
+export SPL_UPSTREAM_COMMIT="$commit"
+cd "$packaging"
+if [[ $kind == native-source ]]; then bash ./build-source.sh; fi
+synopkgland check --json
+synopkgland build --json
+# Review version/provenance and commit synology/ before the next upgrade.

package/assets/init-upstream/version.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Stable tag -> DSM version. Keep all wrapper-owned changes under synology/.
+import {readFileSync, writeFileSync} from 'node:fs';
+const [tag, build, mode] = process.argv.slice(2);
+const match = /^v?((?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*))$/.exec(tag ?? '');
+const file = new URL('./dsm-package.yaml', import.meta.url);
+const source = readFileSync(file, 'utf8');
+const current = /^build: (\d+)\s*$/m.exec(source);
+if (!match || !/^[1-9][0-9]{0,3}$/.test(build ?? '') || !current || Number(build) <= Number(current[1]))
+  throw new Error('Use a stable [v]X.Y.Z tag and an increasing packaging build (1–9999).');
+if (!/^version: .+$/m.test(source)) throw new Error('Missing scaffold version.');
+if (mode !== '--validate') writeFileSync(file, source.replace(/^version: .+$/m, `version: ${match[1]}`).replace(/^build: \d+\s*$/m, `build: ${Number(build)}`));

package/dist/add.js

@@ -8,7 +8,7 @@ import { initFromTemplate, nativeCapabilitySettings } from './init.js';
 import { templatesRoot } from './template-paths.js';
 import { borrowedFiles, borrowedTarget, capabilityOverlays } from './capability-overlays.js';
 import { API_PERMISSIONS_FILE } from './standalone/api-permissions.js';
-import { DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_EXECUTOR_MIN_DSM } from './build-spk/dsm-version.js';
+import { DEFAULT_MIN_DSM, isDsmAtLeast, portalByExecutor, PORTAL_EXECUTOR_MIN_DSM } from './build-spk/dsm-version.js';
 import { loadStandaloneManifest } from './standalone/manifest.js';
 import { PORTAL_REQUIRES_EXECUTOR } from './portal/alias.js';
 function files(root, dir = root) {
@@ -66,13 +66,13 @@ function addPortal(root, result) {
     writeFileSync(manifestPath, setTopLevel(readFileSync(manifestPath, 'utf8'), { ...values, portal: {} }));
     return withNotes({ ...result, added: [...result.added, 'portal'] }, notes);
 }
-/** A portal needs the executor tier, already declared or added in the same call; nothing is written otherwise. */
+/** Before DSM 7.2 a portal needs an executor, already declared or added in the same call. */
 function refuseNoPrivilegePortal(root, rest) {
     const loaded = loadStandaloneManifest(root);
     if (!loaded.ok)
         throw new Error(loaded.errors.map(e => `[${e.code}] ${e.message}`).join('\n'));
     const { rootOps, delegate, webapi } = loaded.manifest.capabilities;
-    if (!rootOps && !delegate && !webapi && !rest.some(name => name === 'root-ops' || name === 'delegate')) {
+    if (portalByExecutor(loaded.manifest.os_min_ver) && !rootOps && !delegate && !webapi && !rest.some(name => name === 'root-ops' || name === 'delegate')) {
         throw new Error(`[STANDALONE_PORTAL_REQUIRES_EXECUTOR] ${PORTAL_REQUIRES_EXECUTOR}`);
     }
 }

package/dist/build-spk/uninstall-wizard.d.ts

@@ -7,7 +7,7 @@ export type UninstallWizardKind = "native" | "container";
 interface UninstallWizardOptions {
     /** The App runs the root executor (rootOps or delegate), which purges DSM's leftovers on uninstall. */
     executor?: boolean;
-    /** The App declares a Login Portal alias (web-config app-portal); only the executor tier can. */
+    /** The App declares a Login Portal alias (web-config app-portal); DSM reloads nginx through INFO. */
     portal?: boolean;
     /** Below DSM 7.2 the executor registered the App's Application Portal entry. */
     portalEntry?: boolean;

package/dist/build-spk/uninstall-wizard.js

@@ -26,7 +26,7 @@ function renderUninstallWizard(t, locale, packageName, kind, { executor = false,
                 ...(kind === "native" ? [{ desc: t("uninstall.retained.native", vars) }] : []),
                 ...(executor ? [{ desc: t("uninstall.executor", vars) }] : []),
                 { desc: t(executor ? "uninstall.appPrivilege.auto" : "uninstall.appPrivilege", vars) },
-                ...(executor && portal ? [{ desc: t("uninstall.portal.auto", vars) }] : []),
+                ...(portal ? [{ desc: t("uninstall.portal.auto", vars) }] : []),
                 ...(executor && portalEntry ? [
                     { desc: t("uninstall.portalEntry", vars) },
                     { desc: portalEntryCleanupCommands(packageName).map((line) => `<code>${html(line)}</code>`).join("<br>") },

package/dist/build-spk/wizard-messages.js

@@ -407,15 +407,15 @@ export const WIZARD_MESSAGES = {
         it: "La disinstallazione rimuove automaticamente le regole di {package} in Pannello di controllo > Privilegi applicazione, così una successiva installazione con lo stesso nome non le applica di nuovo. Solo se questa pulizia non riesce, come segnala la voce synopkgland-executor del registro di sistema, un amministratore deve rimuovere le regole da lì.",
     },
     "uninstall.portal.auto": {
-        en: "After DSM removes the Login Portal alias of {package}, uninstall reloads the web server automatically, so the alias stops at once. Only if this reload failed, as the system log entry synopkgland-executor reports, an administrator can save an application alias in Control Panel > Login Portal > Applications, which reloads the web server, or restart the NAS.",
-        "zh-TW": "DSM 移除 {package} 的登入入口別名後，解除安裝會自動重新載入網頁伺服器，讓該別名立即失效。只有在重新載入失敗時（系統日誌 synopkgland-executor 會記錄），管理員才需要在「控制台」>「登入入口」>「應用程式」儲存任一應用程式別名（會重新載入網頁伺服器），或重新啟動 NAS。",
-        "zh-CN": "DSM 删除 {package} 的登录门户别名后，卸载会自动重新加载网页服务器，使该别名立即失效。只有在重新加载失败时（系统日志 synopkgland-executor 会记录），管理员才需要在“控制面板”>“登录门户”>“应用程序”保存任一应用程序别名（会重新加载网页服务器），或重新启动 NAS。",
-        ja: "DSM が {package} のログイン ポータルのエイリアスを削除した後、アンインストール時に Web サーバーを自動的に再読み込みするため、エイリアスはすぐに無効になります。再読み込みに失敗した場合 (システム ログの synopkgland-executor に記録されます) のみ、管理者が [コントロール パネル] > [ログイン ポータル] > [アプリケーション] でいずれかのアプリケーションのエイリアスを保存する (Web サーバーが再読み込みされます) か、NAS を再起動してください。",
-        ko: "DSM이 {package}의 로그인 포털 별칭을 삭제한 후 제거 과정에서 웹 서버를 자동으로 다시 로드하므로 별칭이 즉시 중지됩니다. 다시 로드가 실패한 경우에만(시스템 로그 synopkgland-executor에 기록됨) 관리자가 제어판 > 로그인 포털 > 응용 프로그램에서 응용 프로그램 별칭을 저장하거나(웹 서버가 다시 로드됨) NAS를 다시 시작하십시오.",
-        de: "Nachdem DSM den Anmeldeportal-Alias von {package} entfernt hat, lädt die Deinstallation den Webserver automatisch neu, sodass der Alias sofort endet. Nur wenn dieses Neuladen fehlschlägt, was der Systemprotokolleintrag synopkgland-executor meldet, muss ein Administrator unter Systemsteuerung > Anmeldeportal > Anwendungen einen Anwendungsalias speichern, wodurch der Webserver neu geladen wird, oder das NAS neu starten.",
-        fr: "Après que DSM a supprimé l’alias du Portail de connexion de {package}, la désinstallation recharge automatiquement le serveur web, si bien que l’alias cesse immédiatement. Seulement si ce rechargement échoue, ce que signale l’entrée synopkgland-executor du journal système, un administrateur doit enregistrer un alias d’application dans Panneau de configuration > Portail de connexion > Applications, ce qui recharge le serveur web, ou redémarrer le NAS.",
-        es: "Después de que DSM elimine el alias del Portal de inicio de sesión de {package}, la desinstalación recarga automáticamente el servidor web, de modo que el alias deja de funcionar al instante. Solo si esta recarga falla, como indica la entrada synopkgland-executor del registro del sistema, un administrador debe guardar un alias de aplicación en Panel de control > Portal de inicio de sesión > Aplicaciones, lo que recarga el servidor web, o reiniciar el NAS.",
-        it: "Dopo che DSM ha rimosso l’alias del Portale di accesso di {package}, la disinstallazione ricarica automaticamente il server web, così l’alias smette subito di funzionare. Solo se questo ricaricamento non riesce, come segnala la voce synopkgland-executor del registro di sistema, un amministratore deve salvare un alias di applicazione in Pannello di controllo > Portale di accesso > Applicazioni, che ricarica il server web, oppure riavviare il NAS.",
+        en: "DSM removes the Login Portal alias of {package} and reloads the web server automatically. The reload can finish after uninstall. If the alias still opens a DSM page, an administrator can save an application alias in Control Panel > Login Portal > Applications to reload the web server.",
+        "zh-TW": "DSM 會移除 {package} 的登入入口別名並自動重新載入網頁伺服器；重新載入可能在解除安裝結束後才完成。如果別名仍開啟 DSM 頁面，管理員可在「控制台」>「登入入口」>「應用程式」儲存任一應用程式別名，以重新載入網頁伺服器。",
+        "zh-CN": "DSM 会删除 {package} 的登录门户别名并自动重新加载网页服务器；重新加载可能在卸载结束后才完成。如果别名仍打开 DSM 页面，管理员可在“控制面板”>“登录门户”>“应用程序”保存任一应用程序别名，以重新加载网页服务器。",
+        ja: "DSM は {package} のログイン ポータルのエイリアスを削除し、Web サーバーを自動的に再読み込みします。再読み込みはアンインストール完了後に終了する場合があります。エイリアスで DSM ページが開く場合、管理者は [コントロール パネル] > [ログイン ポータル] > [アプリケーション] でアプリケーションのエイリアスを保存して再読み込みできます。",
+        ko: "DSM은 {package}의 로그인 포털 별칭을 삭제하고 웹 서버를 자동으로 다시 로드합니다. 다시 로드는 제거 완료 후에 끝날 수 있습니다. 별칭이 여전히 DSM 페이지를 열면 관리자는 제어판 > 로그인 포털 > 응용 프로그램에서 응용 프로그램 별칭을 저장하여 웹 서버를 다시 로드할 수 있습니다.",
+        de: "DSM entfernt den Anmeldeportal-Alias von {package} und lädt den Webserver automatisch neu. Das Neuladen kann nach der Deinstallation enden. Öffnet der Alias weiterhin eine DSM-Seite, kann ein Administrator unter Systemsteuerung > Anmeldeportal > Anwendungen einen Anwendungsalias speichern, um den Webserver neu zu laden.",
+        fr: "DSM supprime l’alias du Portail de connexion de {package} et recharge automatiquement le serveur web. Le rechargement peut se terminer après la désinstallation. Si l’alias ouvre encore une page DSM, un administrateur peut enregistrer un alias d’application dans Panneau de configuration > Portail de connexion > Applications pour recharger le serveur web.",
+        es: "DSM elimina el alias del Portal de inicio de sesión de {package} y recarga automáticamente el servidor web. La recarga puede terminar después de la desinstalación. Si el alias aún abre una página DSM, un administrador puede guardar un alias de aplicación en Panel de control > Portal de inicio de sesión > Aplicaciones para recargar el servidor web.",
+        it: "DSM rimuove l’alias del Portale di accesso di {package} e ricarica automaticamente il server web. Il ricaricamento può terminare dopo la disinstallazione. Se l’alias apre ancora una pagina DSM, un amministratore può salvare un alias di applicazione in Pannello di controllo > Portale di accesso > Applicazioni per ricaricare il server web.",
     },
     "uninstall.portalEntry": {
         en: "Uninstall asks the root executor to remove the Application Portal entry of {package}. If the executor is not running or was never approved, uninstall does not remove the entry; an administrator then runs these commands as root:",

package/dist/cli.js

@@ -421,6 +421,10 @@ export async function runCli(argv) {
         .option("-t, --template <name>", `Template: ${listTemplates().join(" | ")}`)
         .option("--package <id>", "INFO.package (defaults to the directory name)")
         .option("--name <display>", "Display name")
+        .option("--upstream-image <repository>", "compose fork: official image repository; upgrade pins its matching tag and index digest")
+        .option("--upstream-fork", "Create only synology/ inside an upstream source fork (compose or native-go)")
+        .option("--health-path <path>", "compose: actual readiness endpoint; redirects are not followed")
+        .option("--health-status <status>", "compose: expected 2xx readiness status (no default)", Number)
         .option("--ui <vue|plain>", `Native UI ${JSON.parse(readFileSync(join(templatesRoot(), "native-go-vue/frontend/package.json"), "utf8")).dependencies["@synopackageland/ui"]} by default (vue); plain uses ui/app.js`)
         .option("--with <caps>", `Capabilities (comma-separated): ${CAPABILITY_NAMES.join(",")}`)
         .option("--from <compose.yaml>", "compose: import an existing Compose; omit to create an example")
@@ -430,7 +434,7 @@ export async function runCli(argv) {
         .option("--shared-folder-permission <ro|rw>", "Package account permission, defaults to rw")
         .option("--min-dsm <version>", `Minimum DSM version (native templates and binary default to ${DEFAULT_MIN_DSM}, compose to ${CONTAINER_MIN_DSM})`)
         .argument("[dir]", "Target directory", ".")
-        .addHelpText("after", "\nNative projects: native-go, native-python, native-node, native-rust and binary use dsm-package.yaml schema 2.\nCompose projects: compose uses synology-app.yaml; --from imports compose.yaml.\nQuick start: synopkgland init -t native-go --with files,jobs,login my-app\n  cd my-app && synopkgland build\n")
+        .addHelpText("after", "\nNative projects: native-go, native-python, native-node, native-rust and binary use dsm-package.yaml schema 2.\nCompose projects: compose uses dsm-package.yaml schema 2; --from imports compose.yaml.\nQuick start: synopkgland init -t native-go --with files,jobs,login my-app\n  cd my-app && synopkgland build\n")
         .action((dir, options, command) => {
         if (command.parent?.opts().project)
             throw failure("CLI_OPTION_INVALID", "--project does not apply to init.");
@@ -440,6 +444,10 @@ export async function runCli(argv) {
             throw failure("INIT_TEMPLATE_UNKNOWN", `Unknown template: ${options.template}`);
         const targetDir = resolve(dir);
         initFromTemplate(options.template, targetDir, {
+            upstreamFork: options.upstreamFork,
+            upstreamImage: options.upstreamImage,
+            healthPath: options.healthPath,
+            healthStatus: options.healthStatus,
             packageId: options.package,
             displayName: options.name,
             minDsm: options.minDsm,
@@ -457,7 +465,13 @@ export async function runCli(argv) {
                     permission: options.sharedFolderPermission,
                 },
         });
-        stdout(`Created the ${options.template} project at ${targetDir}`);
+        stdout(`Created the ${options.template} project at ${options.upstreamFork ? join(targetDir, "synology") : targetDir}`);
+        if (options.template === "compose")
+            stdout("Select actual compose.web.health path/status before check/build. Redirects are not followed; check does not probe runtime health.");
+        if (options.upstreamFork) {
+            stdout("Read synology/AGENTS.md; configure the official image recipe or the native source hook, then run bash synology/upgrade.sh <upstream-tag> <build-number>.");
+            return;
+        }
         const next = initNextSteps(options.template, dir, existsSync(join(targetDir, "frontend", "package.json")), Boolean(process.env.SYNOPKGLAND_SDK_DIR));
         if (next)
             stdout(next);

package/dist/contract/validate.js

@@ -131,9 +131,9 @@ function validateWebPortal(parsed, contractFile) {
         return [];
     }
     const pos = getValuePosition(doc, ["integration", "web", "portal"]) ?? { line: 1, column: 1 };
-    // A Compose App has no root executor, and only its purge can stop nginx serving the alias after uninstall.
+    // The legacy Compose contract does not generate Application Portal resources.
     return [
-        makeError("CONTRACT_PORTAL_REQUIRES_EXECUTOR", contractSpan(contractFile, pos.line, pos.column, "integration.web.portal"), "A Compose App has no executor and cannot declare an Application Portal: after uninstall DSM does not reload nginx, and only root can remove the alias.", "Remove integration.web.portal; for a sign-in alias, ask an administrator to configure a reverse proxy in DSM."),
+        makeError("CONTRACT_PORTAL_REQUIRES_EXECUTOR", contractSpan(contractFile, pos.line, pos.column, "integration.web.portal"), "The legacy Compose contract does not support integration.web.portal. Use a schema-2 App with a top-level portal declaration and DSM 7.2-64570 or later.", "Migrate to schema 2 and top-level portal, or remove integration.web.portal."),
     ];
 }
 function validateDeveloperString(value, contractFile, path, pos) {

package/dist/e2e/dsm.d.ts

@@ -105,7 +105,7 @@ type SessionPage = {
 /**
  * Registers the signed-in session's cookies (id, did, _SSID) and SynoToken as
  * e2e secrets, so e2e masks them in its report and output, as a request's
- * Playwright call log carries them (t-0498). Returns how many were registered.
+ * Playwright call log carries them. Returns how many were registered.
  */
 export declare function registerDsmSecrets(page?: SessionPage, ledger?: SecretLedger): Promise<number>;
 /**
@@ -136,7 +136,7 @@ export declare function dsmSessionLive(page: Pick<SessionPage, "evaluate">): Pro
 /**
  * `app.open(path)`, once more after net::ERR_ABORTED: about one first
  * navigation in ten was aborted as DSM's desktop navigated on its own, and the
- * next one loaded (t-0499, t-0500). Any other failure, or a second abort, is
+ * next one loaded. Any other failure, or a second abort, is
  * thrown.
  */
 export declare function openPath(app: Pick<App, "open">, path: string): Promise<void>;

package/dist/e2e/dsm.js

@@ -135,7 +135,7 @@ export async function runWithTunnel(command, outer = process.env) {
 // ---- Secrets in output ----------------------------------------------------
 // e2e redacts only the secrets its config declares. A Playwright call log in a
 // run error lists a request's headers, DSM's session cookie among them, and e2e
-// writes it to the report and stdout (t-0498). A value runs to a quote, a
+// writes it to the report and stdout. A value runs to a quote, a
 // backslash or a line end, so a JSON string's escapes end it too.
 const mask = "***";
 // A Cookie or Set-Cookie header, and in it DSM's session (id, _SSID) and device (did) cookies.
@@ -324,7 +324,7 @@ async function e2eSecretLedger() {
 /**
  * Registers the signed-in session's cookies (id, did, _SSID) and SynoToken as
  * e2e secrets, so e2e masks them in its report and output, as a request's
- * Playwright call log carries them (t-0498). Returns how many were registered.
+ * Playwright call log carries them. Returns how many were registered.
  */
 export async function registerDsmSecrets(page = dsmPage(), ledger) {
     const target = ledger ?? await e2eSecretLedger();
@@ -410,7 +410,7 @@ function accountFile(user, env) {
 /**
  * `app.open(path)`, once more after net::ERR_ABORTED: about one first
  * navigation in ten was aborted as DSM's desktop navigated on its own, and the
- * next one loaded (t-0499, t-0500). Any other failure, or a second abort, is
+ * next one loaded. Any other failure, or a second abort, is
  * thrown.
  */
 export async function openPath(app, path) {

package/dist/error-registry.js

@@ -1,7 +1,11 @@
 import { COMPOSE_ERRORS } from "./standalone/compose-errors.js";
 export const ERROR_REGISTRY = {
     ...COMPOSE_ERRORS,
+    INIT_HEALTH_INVALID: { code: "INIT_HEALTH_INVALID", description: "The Compose readiness selection is invalid.", suggestion: "Supply both --health-path and --health-status with the actual endpoint and expected 2xx response; redirects are not followed." },
+    INIT_UPSTREAM_IMAGE_REQUIRED: { code: "INIT_UPSTREAM_IMAGE_REQUIRED", description: "The official upstream image repository was not selected.", suggestion: "Use init --upstream-fork --upstream-image <official-repository> for Compose." },
+    INIT_UPSTREAM_IMAGE_INVALID: { code: "INIT_UPSTREAM_IMAGE_INVALID", description: "The upstream image repository is invalid.", suggestion: "Supply the official repository without a tag or digest; upgrade.sh selects the matching release and resolves its digest." },
     CTL_TRUST_REQUIRED: { "code": "CTL_TRUST_REQUIRED", "description": "App description access requires approval.", "suggestion": "Run synopkgland ctl list with explicit host and approve the candidate batch." },
+    COMPOSE_HEALTH_REQUIRED: { code: "COMPOSE_HEALTH_REQUIRED", description: "Compose web readiness was not selected.", suggestion: "Set compose.web.health.path and expected 2xx status for the actual App; redirects are not followed." },
     CTL_UNSUPPORTED_BACKEND: { "code": "CTL_UNSUPPORTED_BACKEND", "description": "Automatic descriptions require a native SDK backend.", "suggestion": "Disable ctl for binary/Compose wrappers or implement the public contract separately." },
     CTL_DESCRIBE_REQUIRED: { "code": "CTL_DESCRIBE_REQUIRED", "description": "The Go backend has no build-only registry exporter.", "suggestion": "Update the native template and implement --describe using api.DescribeRoutes." },
     CTL_DESCRIBE_FAILED: { "code": "CTL_DESCRIBE_FAILED", "description": "The backend registry export failed.", "suggestion": "Check the backend --describe output and build diagnostics." },
@@ -71,8 +75,8 @@ export const ERROR_REGISTRY = {
         },
         CONTRACT_PORTAL_REQUIRES_EXECUTOR: {
             code: "CONTRACT_PORTAL_REQUIRES_EXECUTOR",
-            description: "The Compose App declares integration.web.portal, but a Compose App has no executor; removing the sign-in alias after uninstall needs root so nginx stops serving it.",
-            suggestion: "Remove integration.web.portal; for a sign-in alias, ask an administrator to configure a reverse proxy in DSM instead.",
+            description: "The legacy Compose contract declares unsupported integration.web.portal.",
+            suggestion: "Use schema 2 with a top-level portal declaration and DSM 7.2-64570+, or remove integration.web.portal.",
         },
         CONTRACT_ACCESS_INVALID: {
             code: "CONTRACT_ACCESS_INVALID",
@@ -526,8 +530,8 @@ export const ERROR_REGISTRY = {
         },
         STANDALONE_PORTAL_REQUIRES_EXECUTOR: {
             code: "STANDALONE_PORTAL_REQUIRES_EXECUTOR",
-            description: "An App without an executor (capabilities.rootOps or delegate) declares portal.",
-            suggestion: "Removing the sign-in alias after uninstall needs root so nginx stops serving it, but an App without escalation uses no root at any stage. Add capabilities.rootOps or delegate (executor level), or remove portal and let an administrator configure a reverse proxy in DSM.",
+            description: "An App targeting DSM below 7.2-64570 declares portal without an executor.",
+            suggestion: "Raise os_min_ver to 7.2-64570 or later to use DSM web-config and INFO nginx reload without root. On DSM 7.1, add an executor capability to register the entry, or remove portal.",
         },
         STANDALONE_LOGIN_STYLE_INVALID: {
             code: "STANDALONE_LOGIN_STYLE_INVALID",

package/dist/host/share-permission.d.ts

@@ -10,7 +10,7 @@
  * extra_values directly, and share permission can change after install.
  *
  * The rows are SYNO.Core.Share.Permission v1 output verbatim. Read the tests
- * before changing the predicate: on the test NAS, `newadmin` has is_writable=false on
+ * before changing the predicate: on the test NAS, `fixtureadmin` has is_writable=false on
  * its own row for `pkgland-p0b` and still writes there, because the
  * `administrators` group row carries the grant. A user-row-only check rejects
  * the only configuration with live proof behind it.

package/dist/host/share-permission.js

@@ -10,7 +10,7 @@
  * extra_values directly, and share permission can change after install.
  *
  * The rows are SYNO.Core.Share.Permission v1 output verbatim. Read the tests
- * before changing the predicate: on the test NAS, `newadmin` has is_writable=false on
+ * before changing the predicate: on the test NAS, `fixtureadmin` has is_writable=false on
  * its own row for `pkgland-p0b` and still writes there, because the
  * `administrators` group row carries the grant. A user-row-only check rejects
  * the only configuration with live proof behind it.

package/dist/init-upstream.d.ts

@@ -0,0 +1,7 @@
+export interface ForkRecipeOptions {
+    upstreamImage?: string;
+    from?: string;
+}
+export declare function validateForkRecipe(template: 'compose' | 'native-go', options: ForkRecipeOptions): void;
+/** CLI-owned packaging recipe; upstream files and history stay untouched. */
+export declare function writeForkScaffold(packaging: string, template: 'compose' | 'native-go', options: ForkRecipeOptions): void;

package/dist/init-upstream.js

@@ -0,0 +1,64 @@
+import { cpSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseDocument } from 'yaml';
+import { API_PERMISSIONS_FILE } from './standalone/api-permissions.js';
+import { parseImageReference } from './images/pin.js';
+export function validateForkRecipe(template, options) {
+    if (template === 'native-go' && options.upstreamImage)
+        throw new Error('[INIT_OPTIONS_UNSUPPORTED] Native forks stage official release binaries or use a source build hook; image options apply only to compose.');
+    if (template !== 'compose')
+        return;
+    if (!options.upstreamImage)
+        throw new Error('[INIT_UPSTREAM_IMAGE_REQUIRED] Compose forks use official images: supply --upstream-image <official-repository>.');
+    const parsed = parseImageReference(options.upstreamImage);
+    if (!parsed || parsed.explicitTag || parsed.digest || !/^[a-z0-9][a-z0-9._:/-]*$/.test(options.upstreamImage) || options.upstreamImage.includes('//'))
+        throw new Error('[INIT_UPSTREAM_IMAGE_INVALID] Supply the official image repository without a tag or digest; upgrade.sh selects the matching upstream release tag.');
+}
+/** CLI-owned packaging recipe; upstream files and history stay untouched. */
+export function writeForkScaffold(packaging, template, options) {
+    const official = template === 'compose';
+    const assets = fileURLToPath(new URL('../assets/init-upstream/', import.meta.url));
+    for (const file of ['upgrade.sh', 'version.mjs', official ? 'update-image.mjs' : 'build-source.sh'])
+        cpSync(join(assets, file), join(packaging, file));
+    const manifest = join(packaging, 'dsm-package.yaml');
+    const doc = parseDocument(readFileSync(manifest, 'utf8'));
+    const service = official ? (doc.toJS().compose.web?.service ?? 'web') : undefined;
+    const recipe = official
+        ? { kind: 'official-image', repository: options.upstreamImage, service, imageTag: 'tag' }
+        : { kind: 'native-source' };
+    writeFileSync(join(packaging, 'upstream-recipe.json'), JSON.stringify(recipe, null, 2) + '\n');
+    doc.set('entry', 'admin-only');
+    if (official) {
+        doc.setIn(['identity_gateway', 'access'], 'dsm-admins');
+        if (!options.from) {
+            const path = join(packaging, 'compose.yaml');
+            const base = parseDocument(readFileSync(path, 'utf8'));
+            base.deleteIn(['services', service, 'command']);
+            base.setIn(['services', service, 'image'], `${options.upstreamImage}:SELECT_UPSTREAM_TAG`);
+            writeFileSync(path, String(base));
+        }
+        doc.setIn(['compose', 'files'], [...doc.toJS().compose.files, 'compose.image.yaml']);
+        writeFileSync(join(packaging, 'compose.image.yaml'), JSON.stringify({ services: { [service]: { image: `${options.upstreamImage}:SELECT_UPSTREAM_TAG` } } }, null, 2) + '\n');
+    }
+    if (!official) {
+        const path = join(packaging, 'backend', API_PERMISSIONS_FILE.go);
+        const policy = JSON.parse(readFileSync(path, 'utf8'));
+        for (const method of Object.keys(policy.methods))
+            policy.methods[method] = 'administrators';
+        writeFileSync(path, JSON.stringify(policy, null, 2) + '\n');
+    }
+    writeFileSync(manifest, String(doc));
+    const guidance = `
+## Integrating an existing open-source App
+
+Keep the upstream fork/history and remote upstream. All wrapper-owned files belong in synology/; never edit upstream files or treat the App as an SDK component. Read synopkgland skill show upstream-fork.
+
+Commit the scaffold, then run bash synology/upgrade.sh <upstream-tag> <build-number>. It fetches the exact tag, verifies ancestry/untouched upstream files, merges, derives version/provenance, checks and builds. Commit synology/ before upgrading again. It does not publish or touch a NAS.
+
+${official ? 'Default: use the upstream official image. upgrade.sh updates its release tag and resolves an OCI index/manifest digest through synopkgland images pin, writing only synology/compose.image.yaml. Container Manager downloads that pinned official image at install. Configure upstream-recipe.json repository/service and imageTag: tag (exact upstream tag) or version (strip v only when upstream image naming requires it). Review multi-architecture support and upstream source/license correspondence. The SELECT_UPSTREAM_TAG placeholder must be replaced by a successful upgrade before check/build.' : 'Native App: implement build-source.sh as the native payload hook; it deliberately fails until implemented. Stage official release binaries pinned by SHA-256 (the OpenList route), or compile the merged source with a source build hook. Verify the release digest before staging architecture-specific daemon.targets; keep the SDK management shell separate.'}
+
+Use DSM administrator identity without an additional App password, an OIDC/SSO server or upstream source changes. Prefer supported trusted-header/proxy auth (FreshRSS), otherwise disable upstream login/enable guest behind the administrator-only gateway after a bounded first bootstrap (Uptime Kuma disableAuth). The third shipped pattern is the existing SDK 0.17.0 token adapter: mode: token, access: dsm-admins, entry: admin-only. OpenList obtains its native API token with the unmodified admin token CLI while stopped, stores it package-private 0600 under a 0700 directory, and the gateway injects Authorization server-side after DSM admission; packaging never delivers it to the browser. All DSM admins share one upstream admin; token reset requires package restart; WebDAV keeps its own native credentials. The upstream admin token/settings APIs remain unchanged. Verify actual DSM admission/revocation separately. Use supported config, environment, argv or proxy adapters. Every App lifecycle phase runs as the package UID. For upstream fixed-UID data directories, currently provide a synology/ startup adapter or writable path without root/chown; replace it with the framework ownership mechanism when available. Preserve licenses and the full source/component inventory.
+`;
+    writeFileSync(join(packaging, 'AGENTS.md'), readFileSync(join(packaging, 'AGENTS.md'), 'utf8') + guidance);
+}

package/dist/init.d.ts

@@ -16,6 +16,10 @@ export interface InitOptions {
     ui?: "plain" | "vue";
     with?: string[];
     from?: string;
+    upstreamFork?: boolean;
+    upstreamImage?: string;
+    healthPath?: string;
+    healthStatus?: number;
     /** native-go: `install.sharedFolder` (select from the NAS, or create one). key defaults to "shared", permission to "rw". */
     sharedFolder?: {
         mode: "select" | "create";