@synopackageland/cli 0.17.4 → 0.17.6

package/dist/standalone/resource.d.ts

@@ -2,6 +2,7 @@ import type { ComposeApp } from "./compose.js";
 import type { Capabilities } from "./manifest.js";
 import { type SharedFolder } from "./shared-folder.js";
 import { type PortalPackage } from "../portal/package.js";
+import { type NativeGatewayPlan } from './native-gateway.js';
 /**
  * `conf/resource` for a native package: only DSM's official `data-share`,
  * `systemd-user-unit` and `web-config` workers, in a fixed key order.
@@ -9,6 +10,8 @@ import { type PortalPackage } from "../portal/package.js";
  */
 export declare function renderStandaloneResource(m: {
     package: string;
+    os_min_ver?: string;
+    identityGateway?: NativeGatewayPlan;
     capabilities: Capabilities;
     compose?: ComposeApp;
     sharedFolder?: SharedFolder;

package/dist/standalone/resource.js

@@ -1,6 +1,7 @@
 import { renderDockerProjectResource } from "../build-spk/resource-worker.js";
 import { sharedFolderResource } from "./shared-folder.js";
 import { portalResource } from "../portal/package.js";
+import { nativeGatewayResource } from './native-gateway.js';
 /**
  * `conf/resource` for a native package: only DSM's official `data-share`,
  * `systemd-user-unit` and `web-config` workers, in a fixed key order.
@@ -8,13 +9,14 @@ import { portalResource } from "../portal/package.js";
  */
 export function renderStandaloneResource(m, portal) {
     const dataShare = m.sharedFolder && sharedFolderResource(m.package, m.sharedFolder);
+    const webConfig = { ...(portal ? portalResource()['web-config'] : {}), ...nativeGatewayResource(m) };
     const resource = {
         ...(m.compose && !m.compose.plan.mounts_blocked
             ? renderDockerProjectResource(m.package, "compose", false, m.compose.plan.project_name)
             : {}),
         ...(dataShare ? { "data-share": dataShare } : {}),
         ...(m.capabilities.jobs ? { "systemd-user-unit": {} } : {}),
-        ...(portal ? portalResource() : {}),
+        ...(Object.keys(webConfig).length ? { 'web-config': webConfig } : {}),
     };
     return Object.keys(resource).length > 0
         ? JSON.stringify(resource)

package/dist/standalone/spk.js

@@ -1,3 +1,4 @@
+import { nativeGatewaySupported, nativeGatewaySdk, renderNativeGatewayConfig, NATIVE_GATEWAY_CONFIG, legacyGatewayNotice, gatewayEntryPath } from './native-gateway.js';
 import { portalInfoFields } from "../portal/info.js";
 import { sdkSource } from "../runtime/sdk-source.js";
 import { resolvedSdkLaunch } from "../contract/app-launch.js";
@@ -116,6 +117,10 @@ export async function assembleStandaloneSpk(options) {
                 chmodSync(target, EXEC_MODE);
             }
             writeFile(join(staging, "package", GATEWAY_CONFIG_PATH), identityGatewayConfig(manifest));
+            if (nativeGatewaySupported(manifest))
+                writeFile(join(staging, 'package', NATIVE_GATEWAY_CONFIG), renderNativeGatewayConfig(manifest));
+            if (!nativeGatewaySdk(manifest.identityGateway.sdk))
+                writeFile(join(staging, 'package/ui/sso/open.html'), legacyGatewayNotice());
         }
         if (manifest.capabilities.jobs) {
             if (!options.backgroundWorker)
@@ -208,8 +213,11 @@ export async function assembleStandaloneSpk(options) {
             .digest("hex");
         writeFile(join(staging, "sdk-package.json"), JSON.stringify({
             schema: 2,
+            ...(manifest.lifecycleTimeouts ? { lifecycleTimeouts: manifest.lifecycleTimeouts } : {}),
+            ...("timeoutSeconds" in manifest.backend && manifest.backend.timeoutSeconds ? { operationSeconds: manifest.backend.timeoutSeconds } : {}),
             ...(options.apiDescription ? { ctl: { hash: options.apiDescription.sha256, registry: options.apiRegistry } } : {}),
             backend: manifest.backend.kind,
+            ...(nativeGatewaySupported(manifest) ? { native_gateway: { sdk: manifest.identityGateway.sdk, listen: manifest.identityGateway.listen } } : {}),
             launch: resolvedSdkLaunch(manifest),
             capabilities: Object.keys(manifest.capabilities).sort(),
             ...(manifest.compose
@@ -236,7 +244,7 @@ export async function assembleStandaloneSpk(options) {
             writeFile(join(staging, "conf", "resource"), resource);
         if (manifest.capabilities.jobs) {
             mkdirSync(join(staging, BACKGROUND_UNIT_DIR), { recursive: true });
-            writeFile(join(staging, BACKGROUND_UNIT_DIR, backgroundUnitName(manifest.package)), renderBackgroundUnit(manifest.package, isBridgeBackend(manifest.backend) ? BRIDGE_WORKER_ARGS : []));
+            writeFile(join(staging, BACKGROUND_UNIT_DIR, backgroundUnitName(manifest.package)), renderBackgroundUnit(manifest.package, isBridgeBackend(manifest.backend) ? BRIDGE_WORKER_ARGS : [], manifest.daemon?.timeouts.stop ?? manifest.lifecycleTimeouts?.stop ?? 30));
         }
         mkdirSync(join(staging, "scripts"));
         for (const name of LIFECYCLE_SCRIPTS) {
@@ -265,6 +273,7 @@ export async function assembleStandaloneSpk(options) {
                 ? renderSharedFolderUpgradeWizardFiles(manifest.package, folder)
                 : {}),
             ...renderUninstallWizardFiles(manifest.package, "native", {
+                composeData: manifest.compose?.plan.app_data,
                 executor: Boolean(options.executor),
                 portal: Boolean(portal),
                 portalEntry: Boolean(manifest.portal && portalByExecutor(manifest.os_min_ver)),
@@ -324,7 +333,7 @@ export function renderInfo(manifest, arch, checksum, executorDigest) {
         if (manifest.identityGateway)
             fields.push([
                 "adminurl",
-                `/webman/3rdparty/${manifest.package}/sso/open.cgi`,
+                gatewayEntryPath(manifest),
             ]);
     }
     const backend = manifest.backend;
@@ -341,7 +350,9 @@ export function renderInfo(manifest, arch, checksum, executorDigest) {
         if (text?.description)
             fields.push([`description_${DSM_LANGS[locale]}`, text.description]);
     }
-    return portalInfoFields(fields, Boolean(manifest.portal)).map(([key, value]) => `${key}=${quote(value)}\n`).join("");
+    if (nativeGatewaySupported(manifest))
+        fields.push(['startstop_restart_services', 'nginx.service']);
+    return portalInfoFields(fields, Boolean(manifest.portal) || nativeGatewaySupported(manifest)).map(([key, value]) => `${key}=${quote(value)}\n`).join("");
 }
 function copyUiTree(source, target) {
     for (const entry of ["app.js", "app.css"]) {

package/dist/standalone/uninstall-hook.js

@@ -22,6 +22,7 @@ export function renderUninstallHook(manifest) {
     if (!purge)
         return "";
     const pkg = manifest.package;
+    const reserve = Math.min(5, Math.max(1, Math.floor(purge.timeout / 4)));
     const env = [
         "PATH=/usr/bin:/bin", 'HOME="$hook_var"', 'TMPDIR="$hook_var/tmp"',
         ...Object.entries(purge.env).map(([key, value]) => `${key}=${word(value)}`),
@@ -47,7 +48,11 @@ ${manifest.uninstall?.state ? wizardFlag("delete_state", ["pkgwizard_delete_stat
   # DSM's bash logs a failed kill to syslog even with 2>/dev/null, so a
   # finished hook is looked up in /proc wherever there is one.
   hook_running() {
-    if [ -d /proc/self ]; then [ -d "/proc/$hook_pid" ]; else kill -0 "$hook_pid" 2>/dev/null; fi
+    if [ -d /proc/self ]; then
+      [ -r "/proc/$hook_pid/stat" ] || return 1
+      case "$(sed 's/.*) //' "/proc/$hook_pid/stat" 2>/dev/null)" in Z*|X*|'') return 1 ;; esac
+      return 0
+    else kill -0 "$hook_pid" 2>/dev/null; fi
   }
   # A process in /proc whose group is the hook's ("pid (comm) state ppid pgrp ...").
   hook_group_running() {
@@ -62,19 +67,27 @@ ${manifest.uninstall?.state ? wizardFlag("delete_state", ["pkgwizard_delete_stat
       kill -"$1" "$hook_pid"
     fi
   }
-  hook_waited=0
-  while hook_running && [ "$hook_waited" -lt ${purge.timeout} ]; do
-    sleep 1
-    hook_waited=$((hook_waited + 1))
+  hook_now() { if [ -r /proc/uptime ]; then awk '{print int($1)}' /proc/uptime; else date +%s; fi; }
+  hook_until=$(( $(hook_now) + ${purge.timeout} ))
+  hook_work_until=$((hook_until - ${reserve}))
+  while hook_running && [ "$(hook_now)" -lt "$hook_work_until" ]; do
+    sleep 0.1
   done
   hook_failure=
   if hook_running; then
     hook_signal TERM
-    sleep 1
+    hook_grace_until=$((hook_until - 1))
+    while hook_group_running && [ "$(hook_now)" -lt "$hook_grace_until" ]; do sleep 0.1; done
     hook_signal KILL
-    wait "$hook_pid" 2>/dev/null
-    hook_failure="timeout after ${purge.timeout} s"
+    while hook_running && [ "$(hook_now)" -lt "$hook_until" ]; do sleep 0.1; done
+    if hook_running || hook_group_running; then
+      echo cleanup-pending >"$hook_var/uninstall-hook.pending"
+    else
+      wait "$hook_pid" 2>/dev/null
+    fi
+    hook_failure="timeout after ${purge.timeout} s; cleanup may be pending"
   else
+    rm -f "$hook_var/uninstall-hook.pending"
     wait "$hook_pid"
     hook_status=$?
     [ "$hook_status" -eq 0 ] || hook_failure="exit $hook_status"

package/dist/standalone/uninstall.d.ts

@@ -19,7 +19,7 @@ export interface UninstallPurge {
     exec: string;
     args: string[];
     env: Record<string, string>;
-    /** Seconds, 2..120. */
+    /** Seconds, 2..3600. */
     timeout: number;
     /** A root/<name>.sh the executor runs at uninstall, only while its approval is live. */
     root?: string;

package/dist/standalone/uninstall.js

@@ -16,7 +16,7 @@ export function readUninstall(value, context, fail) {
     if (value === undefined)
         return undefined;
     const invalid = () => {
-        fail({ code: "UNINSTALL_INVALID", message: "uninstall accepts only purge {exec, args, env, timeout, root} and state {items: [{key}]}; exec must be a fixed executable inside the package (not in executor/ or root/), and timeout is an integer from 2 to 120 seconds." });
+        fail({ code: "UNINSTALL_INVALID", message: "uninstall accepts only purge {exec, args, env, timeout, root} and state {items: [{key}]}; exec must be a fixed executable inside the package (not in executor/ or root/), and timeout is an integer from 2 to 3600 seconds." });
         return undefined;
     };
     if (!record(value) || Object.keys(value).some(k => !FIELDS.has(k)))
@@ -54,7 +54,7 @@ function readPurge(value, context, fail) {
         || Object.entries(env).some(([k, v]) => !envKey(k) || k.startsWith("SYNOPKGLAND_") || !token(v)))
         return "invalid";
     const timeout = value.timeout ?? 60;
-    if (!Number.isInteger(timeout) || timeout < 2 || timeout > 120)
+    if (!Number.isInteger(timeout) || timeout < 2 || timeout > 3600)
         return "invalid";
     const root = value.root;
     if (root !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.17.4",
+  "version": "0.17.6",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "0.17.6",
+    "@synopackageland/templates": "0.17.8",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/reference/compose.md

@@ -39,6 +39,12 @@ scripts run as the package account; containers are managed by Container Manager.
 
 Set `compose.startup_timeout_seconds: 600` for a slow cold start or migration.
 Omitting it uses 120 seconds; only integers from 2 through 900 are accepted.
+Lock waiting, status, readiness, stability and handoff share that deadline; there
+is no extra fixed handoff allowance. The cap is a policy bound, not a measured
+DSM lifecycle limit. `daemon: {timeouts: {stop: 120, status: 15, uninstall: 300}}`
+configures the other lifecycle phases without declaring a daemon payload.
+A transient health failure closes new ingress while the running App gets one
+operation-budget recovery window; authority or generation failures stop at once.
 Use a matching SDK that implements the field and rebuild the App; older planners
 are rejected for explicit budgets. The SDK plan drives generated daemon start
 and supplies every container with `SYNOPKGLAND_STARTUP_BUDGET_SECONDS`, overriding
@@ -386,3 +392,28 @@ Do not silently switch networking, add Docker socket access, run an App hook as
 root or delete DSM configuration to claim compatibility.
 
 Compose web health is required before check/build; init has no guessed endpoint or status. Select both `--health-path` and `--health-status`, or edit `compose.web.health`. Readiness does not follow redirects. Static check is not an HTTP or arbitrary-UID/storage preflight. For official-image upstream packaging and DSM login, read [upstream-fork.md](upstream-fork.md).
+
+
+## Named volumes and uninstall
+
+The SDK planner and lock inventory all current project-owned named volumes as
+App data, with exact names. Compose alone never selects an executor or root
+permissions. The package account does not delete named volumes or access Docker.
+
+Before confirmation, the uninstall wizard states that container data volumes
+are kept even when delete-data is selected, and lists the current exact names.
+Only exact `SYNOPKG_PKG_STATUS=UNINSTALL` with an affirmative
+`pkgwizard_remove_additional` (or supported mirror/legacy alias) clears the
+package data/config/home contents the package account can clear. Upgrade, stop,
+unknown status and keep preserve data. Unsafe paths and remnants are reported.
+
+On delete-data uninstall with a nonempty volume inventory, generated postuninst
+appends nine-language native text through `SYNOPKG_TEMP_LOGFILE`, preserving
+existing text. It says plainly the listed volumes were NOT deleted and ends
+with `COMPOSE_DATA_RETAINED`. The list is the current planner/lock inventory,
+not a runtime existence check; volumes retired by older versions may also remain.
+No full-data-deletion success is claimed and no unverified deletion path is given.
+Administrator cleanup procedures, executor-tier Apps and storage redesign are
+out of scope. Final DSM native UI acceptance remains required.
+
+See the SDK's [Compose App data contract](https://github.com/synopackageland/syno-pkg-land-sdk/blob/main/docs/compose-app-data.md).

package/skills/reference/create.md

@@ -113,7 +113,7 @@ root:
     migrate: {}          # 沒有 run、job：只作為 start 步驟
 ```
 
-start、stop 步驟與 `uninstall.purge.root` 都以 root、無 session 執行，只在管理員核准有效時跑；這些程式不能宣告 run 或 job（session 要用時以另一個名稱設定，可指向同一份內容）。start 步驟在新版本第一次啟動、executor 開 socket 並回讀核准任務之後執行，最多 60 秒；執行期間 executor 只回應 `status`（`state: "starting"`），其他請求回可重試的 `EXECUTOR_STARTING`，DSM 視窗的核准會等它結束，狀態讀取則立即回 `executor_starting`、由 SDK 面板自行重試，失敗只寫進 executor log，不擋啟動；同一版本不重跑，程式要能重複執行。結果由 executor `status` 的 `start_step` 讀取（`pending`、`ok`、`failed`，含 exit 與 output）。DSM 的 start 只寫入要求就返回，所以 `dsm-scripts/postinst`、`postupgrade`、`start` 看不到它的結果；root 的清理或遷移放 `root.start`，非特權的收尾放 `dsm-scripts/`。宣告 `root.start` 會改變 policy digest，需要管理員重新核准；沒有宣告的 App policy 不變。需要 SDK 0.10.3 以上。
+start、stop 步驟與 `uninstall.purge.root` 都以 root、無 session 執行，只在管理員核准有效時跑；這些程式不能宣告 run 或 job（session 要用時以另一個名稱設定，可指向同一份內容）。start 步驟在新版本第一次啟動、executor 開 socket 並回讀核准任務之後執行，預設最多 60 秒；若宣告 lifecycle budget，則從核准的 start 剩餘預算扣除收尾餘裕；執行期間 executor 只回應 `status`（`state: "starting"`），其他請求回可重試的 `EXECUTOR_STARTING`，DSM 視窗的核准會等它結束，狀態讀取則立即回 `executor_starting`、由 SDK 面板自行重試，失敗只寫進 executor log，不擋啟動；同一版本不重跑，程式要能重複執行。結果由 executor `status` 的 `start_step` 讀取（`pending`、`ok`、`failed`，含 exit 與 output）。DSM 的 start 只寫入要求就返回，所以 `dsm-scripts/postinst`、`postupgrade`、`start` 看不到它的結果；root 的清理或遷移放 `root.start`，非特權的收尾放 `dsm-scripts/`。宣告 `root.start` 會改變 policy digest，需要管理員重新核准；沒有宣告的 App policy 不變。需要 SDK 0.10.3 以上。
 
 schema 是 executor 的封閉子集（每個 object 都要 `additionalProperties: false`，key `[a-z0-9_]`，pattern 為 RE2）。這些設定需要支援它們的 SDK executor（`EXECUTOR_ROOT_PROGRAMS_UNSUPPORTED`）。preupgrade 呼叫 `executor/lifecycle stop --upgrade`；舊 SDK 的 helper 不認得此旗標時改用一般 stop。
 

package/skills/reference/lifecycle.md

@@ -108,3 +108,28 @@ A silent upgrade has no wizard values; use a default.
   change they made.
 - An upgrade runs the old package's preuninst and postuninst; check
   `SYNOPKG_PKG_STATUS` before deleting anything.
+
+## Work budgets
+
+Use existing `daemon.timeouts` for start/stop/status/uninstall (defaults
+30/30/5/60 seconds). Start/stop/uninstall accept 2–3600 seconds and status accepts
+1–3600. A `daemon` containing only `timeouts` declares budgets without an
+executable, including background and Compose Apps; Compose start still uses
+`compose.startup_timeout_seconds` (120, 2–900). Background user-manager recovery
+uses the start allowance and its generated package user unit uses the stop
+allowance with `KillMode=control-group`.
+
+`backend.timeout_seconds` owns request/operation work. Binary and Compose Apps
+without a CGI request setting can enlarge the shared operation allowance through
+`daemon.timeouts.status` above its 60-second default. Generated gateway and
+approved executor configurations inherit it; nested calls use remaining time and
+leave response reserve. Budget changes in the protected policy require renewed
+approval and do not change token/session/grant lifetimes.
+
+`uninstall.purge.timeout` accepts 2–3600 seconds and includes termination reserve.
+A timeout is logged and may leave `uninstall-hook.pending`; the uninstall may
+continue. The executor helper's JSON state distinguishes `accepted`,
+`cleanup-complete` and `cleanup-pending`. An exit of zero acknowledges the retained
+request and does not prove cleanup finished. Unconfirmed cleanup retains protected
+state for a later retry. DSM's outer install/uninstall deadline is not established
+by these settings.