@synopackageland/cli 0.23.0 → 0.23.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.23.1 (2026-10-22)
+
+- Build SDK/App 0.23.1 with its verified immutable executor/v0.20.0 digests; retain support for SDK/App 0.23.0. This enables the SDK HTTP transfer error-status fix without changing executor or lifecycle payloads.
+- Include the native HTTPS shutdown/start port-release fix and recognize its exact diagnostic prefix when inspecting Portal and background-job lifecycle scripts. Keep templates 0.23.0 and the existing UI pin.
+
 ## 0.23.0 (2026-10-21)
 
 - Validate the explicit OIDC `browser_redirect` contract before packaging and pin templates/SDK 0.23.0.

package/dist/runtime/executor-digests.json

@@ -9,5 +9,16 @@
             "armv7": "256fb348b275da7ac5728a3cb7cb7c65660de0d5c2c59430ab4f5ade1b0a3681"
         },
         "goToolchain": "go1.26.9"
+    },
+    "0.23.1": {
+        "x86_64": "e27cfeb85fed221b06f9c58166f02c0f701a724308cd17c96a43a843a0b5c4aa",
+        "aarch64": "908db00cbd37d072f6ffc339e7bca24da5efb8cddd4befcbad02c7398beb7191",
+        "armv7": "a0f35d62ec80a1bf3fb49f5e2d1a5f7576eda569a6fd0695084cec6cb8e100bc",
+        "lifecycle": {
+            "x86_64": "9bb53301670b43cdcd6e21cebac99ab7abd82962d874f32423a81e6cb49d4972",
+            "aarch64": "38fe873c86eb102c850baa1f304114a83a31d1df72defd22792bc37610fec9bb",
+            "armv7": "256fb348b275da7ac5728a3cb7cb7c65660de0d5c2c59430ab4f5ade1b0a3681"
+        },
+        "goToolchain": "go1.26.9"
     }
 }

package/dist/runtime/sdk-source.js

@@ -76,7 +76,7 @@ function goMod(backendDir) {
     }
 }
 /** SDK releases that reuse an immutable executor release with identical payload bytes. */
-const EXECUTOR_RELEASES = { '0.21.0': '0.20.0', '0.21.1': '0.20.0', '0.22.0': '0.20.0', '0.23.0': '0.20.0' };
+const EXECUTOR_RELEASES = { '0.21.0': '0.20.0', '0.21.1': '0.20.0', '0.22.0': '0.20.0', '0.23.0': '0.20.0', '0.23.1': '0.20.0' };
 /**
  * The module directories of one SDK version. SYNOPKGLAND_SDK_DIR names a
  * local sdk checkout (development and gates only); otherwise modules come from

package/dist/standalone/inspect-spk.js

@@ -1,6 +1,6 @@
 import { readInstallSettings, settingsInstallSteps, settingsConfig, renderSettingsHook } from './install-settings.js';
 import { nativePortal } from "./portal.js";
-import { nativeGatewaySupported, renderNativeGatewayConfig, renderNativeGatewayPrepare, NATIVE_GATEWAY_CONFIG, gatewayEntryPath } from './native-gateway.js';
+import { nativeGatewaySupported, renderNativeGatewayConfig, renderNativeGatewayDiagnostic, renderNativeGatewayPrepare, NATIVE_GATEWAY_CONFIG, gatewayEntryPath } from './native-gateway.js';
 import { inspectPortalInfo } from "../portal/info.js";
 import { isDeepStrictEqual } from "node:util";
 import { inspectApiDescription } from "./api-description-inspect.js";
@@ -36,7 +36,7 @@ import { renderNativePrivilege } from "../build-spk/native-lifecycle.js";
 import { renderUiConfig } from "./dsm-window.js";
 import { identityGatewayConfig, gatewayAdmissionReport, gatewayAdmissionPolicy, readIdentityGateway, } from "./identity-gateway.js";
 import { checkCgiBinary } from "./binary.js";
-import { renderStandaloneScript } from "./lifecycle.js";
+import { matchesStandaloneScript, renderStandaloneScript } from "./lifecycle.js";
 import { listPortExposures, loadCompose } from "../compose/analyze.js";
 import { uninstallCleanup, } from "../runtime/uninstall-cleanup.js";
 import { PORTAL_JSON_RELPATH, PORTAL_MUSTACHE_RELPATH, renderPortalJson, renderPortalLifecycle, renderPortalMustache, renderPortalWizardStep, } from "../portal/package.js";
@@ -209,7 +209,7 @@ export async function inspectSpk(spkPath, expectedKind) {
             ? await checkDaemon(dir, info, paths, payload, findings, hasExecutor, background, combined, nativeGateway, uninstallHook?.uninstall)
             : undefined;
         if (background)
-            checkBackground(dir, info, payload, findings, hasExecutor, daemon, kind !== "native-go", metadata.lifecycleTimeouts);
+            checkBackground(dir, info, payload, findings, hasExecutor, daemon, kind !== "native-go", metadata.lifecycleTimeouts, nativeGateway);
         let executor;
         if ((metadata.capabilities ?? []).some((name) => name === "rootOps" || name === "delegate" || name === "webapi") ||
             paths.has("executor/executor")) {
@@ -701,8 +701,7 @@ async function inspectUnifiedCompose(dir, payload, metadata, findings) {
             "postupgrade",
             "start-stop-status",
         ])
-            if (readOptional(join(dir, "scripts", hook)) !==
-                renderStandaloneScript(hook, manifest))
+            if (!matchesStandaloneScript(hook, manifest, readOptional(join(dir, "scripts", hook))))
                 throw new Error(`unexpected scripts/${hook}`);
         if (appScripts.length)
             base.appScripts = appScripts;
@@ -897,8 +896,7 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
         if (readFileSync(join(unpacked, "daemon/config.json"), "utf8") !== JSON.stringify(expectedConfig) + '\n')
             throw new Error("non-canonical daemon config");
         for (const hook of ["start-stop-status", "preupgrade", "preuninst"]) {
-            if (readFileSync(join(dir, "scripts", hook), "utf8") !==
-                renderStandaloneScript(hook, nativeGateway ? { ...manifest, os_min_ver: info.os_min_ver, identityGateway: nativeGateway } : manifest))
+            if (!matchesStandaloneScript(hook, nativeGateway ? { ...manifest, os_min_ver: info.os_min_ver, identityGateway: nativeGateway } : manifest, readFileSync(join(dir, "scripts", hook), "utf8")))
                 findings.push(`daemon scripts/${hook} does not match the fixed lifecycle`);
         }
         return daemon;
@@ -1120,7 +1118,7 @@ function checkConf(dir, findings, kind, background, sharedFolder, pkg, portal, c
     }
 }
 /** The opt-in package user unit must be exactly what the generator writes. */
-function checkBackground(dir, info, payload, findings, executor, daemon, bridge = false, lifecycleTimeouts) {
+function checkBackground(dir, info, payload, findings, executor, daemon, bridge = false, lifecycleTimeouts, nativeGateway) {
     const pkg = info.package;
     if (!pkg)
         return;
@@ -1141,16 +1139,17 @@ function checkBackground(dir, info, payload, findings, executor, daemon, bridge
             renderBackgroundUnit(pkg, bridge ? BRIDGE_WORKER_ARGS : [], daemon?.timeouts.stop ?? lifecycleTimeouts?.stop ?? 30)) {
         findings.push(`${BACKGROUND_UNIT_DIR} must contain only the fixed ${unit} (runs as the package account, no User=, no root)`);
     }
-    if (read("scripts/start-stop-status") !==
-        renderStandaloneScript("start-stop-status", {
-            package: pkg,
-            lifecycleTimeouts,
-            ...(daemon ? { daemon } : {}),
-            capabilities: {
-                jobs: { worker: "sha256-v1" },
-                ...(executor ? { rootOps: true } : {}),
-            },
-        }))
+    if (!matchesStandaloneScript("start-stop-status", {
+        package: pkg,
+        os_min_ver: info.os_min_ver,
+        ...(nativeGateway ? { identityGateway: nativeGateway } : {}),
+        lifecycleTimeouts,
+        ...(daemon ? { daemon } : {}),
+        capabilities: {
+            jobs: { worker: "sha256-v1" },
+            ...(executor ? { rootOps: true } : {}),
+        },
+    }, read("scripts/start-stop-status")))
         findings.push("background scripts/start-stop-status does not match the fixed synosystemctl lifecycle");
 }
 /**
@@ -1204,16 +1203,14 @@ function checkSharedFolder(dir, findings, pkg, folder, selected = false, portal,
         findings.push(`WIZARD_UIFILES/${name} is not a wizard file produced by ${source}`);
     if (selected) {
         for (const hook of ["preinst", "postinst"]) {
-            if (readOptional(join(dir, "scripts", hook)) !==
-                renderStandaloneScript(hook, lifecycleManifest))
+            if (!matchesStandaloneScript(hook, lifecycleManifest, readOptional(join(dir, "scripts", hook))))
                 findings.push(`scripts/${hook} does not match the fixed install-selected draft handling`);
         }
     }
     if (!folder && !portal)
         return;
     for (const hook of ["postinst", "postupgrade"]) {
-        if (readOptional(join(dir, "scripts", hook)) !==
-            renderStandaloneScript(hook, lifecycleManifest)) {
+        if (!matchesStandaloneScript(hook, lifecycleManifest, readOptional(join(dir, "scripts", hook)))) {
             findings.push(`scripts/${hook} does not match the fixed script declared by ${folder ? "install.sharedFolder" : "portal"}`);
         }
     }
@@ -1313,7 +1310,15 @@ async function recoverPortal(dir, info, appId, paths, payload, findings, nativeG
                     identityGateway: nativeGateway,
                 })
                 : "";
-            if (!readOptional(join(dir, "scripts", hook))?.startsWith(`#!/bin/sh\n${prepare}${renderPortalLifecycle(hook, portal)}`))
+            const diagnostic = renderNativeGatewayDiagnostic({
+                package: info.package,
+                os_min_ver: info.os_min_ver,
+                identityGateway: nativeGateway,
+            }, hook);
+            const script = readOptional(join(dir, "scripts", hook));
+            // The fixed native diagnostics precede preparation in current scripts;
+            // released scripts can still start directly with preparation.
+            if (![diagnostic, ""].some(prefix => script?.startsWith(`#!/bin/sh\n${prefix}${prepare}${renderPortalLifecycle(hook, portal)}`)))
                 throw new Error(hook);
         }
         return portal;

package/dist/standalone/lifecycle.d.ts

@@ -1,3 +1,5 @@
 import type { StandaloneManifest } from "./manifest.js";
 /** Package-account lifecycle hooks for CGI, daemon and background packages. */
 export declare function renderStandaloneScript(name: string, manifest: StandaloneManifest): string;
+/** Accept the exact current, diagnostic-only, and released lifecycle variants. */
+export declare function matchesStandaloneScript(name: string, manifest: StandaloneManifest, actual: string | undefined): boolean;

package/dist/standalone/lifecycle.js

@@ -1,6 +1,6 @@
 import { renderSettingsHook } from './install-settings.js';
 import { renderComposeRetainedData } from "../build-spk/compose-retained-data.js";
-import { renderNativeGatewayPrepare } from './native-gateway.js';
+import { renderNativeGatewayDiagnostic, renderNativeGatewayPortWait, renderNativeGatewayPrepare } from './native-gateway.js';
 import { renderComposeDiagnosis } from "../build-spk/compose-diagnosis.js";
 import { composeDaemon, renderComposeInstall } from "./compose.js";
 import { renderBackgroundControl, renderBackgroundWorkerStart, renderBackgroundWorkerStop, renderUserManagerRecovery, backgroundUnitName, } from "./background.js";
@@ -16,12 +16,23 @@ const UNINSTALL_ONLY = '[ "${SYNOPKG_PKG_STATUS:-}" = UPGRADE ] || synopkgland_u
 export function renderStandaloneScript(name, manifest) {
     const script = renderStandaloneScriptInternal(name, manifest);
     const prepared = ['postinst', 'postupgrade'].includes(name) ? renderNativeGatewayPrepare(manifest) : '';
-    const prefix = renderSettingsHook(name, manifest) + prepared;
+    const prefix = renderNativeGatewayDiagnostic(manifest, name) + renderNativeGatewayPortWait(manifest, name) + renderSettingsHook(name, manifest) + prepared;
     const sdk = prefix ? script.replace('#!/bin/sh\n', () => '#!/bin/sh\n' + prefix) : script;
     return manifest.appScripts?.some((app) => app === name)
         ? composeAppScript(name, sdk)
         : sdk;
 }
+/** Accept the exact current, diagnostic-only, and released lifecycle variants. */
+export function matchesStandaloneScript(name, manifest, actual) {
+    const expected = renderStandaloneScript(name, manifest);
+    if (actual === expected)
+        return true;
+    const diagnostic = renderNativeGatewayDiagnostic(manifest, name);
+    const wait = renderNativeGatewayPortWait(manifest, name);
+    const diagnosticOnly = wait ? expected.replace(wait, '') : expected;
+    return (wait !== '' && actual === diagnosticOnly) ||
+        (diagnostic !== '' && actual === diagnosticOnly.replace(diagnostic, ''));
+}
 function renderStandaloneScriptInternal(name, manifest) {
     if (manifest.compose) {
         const native = {

package/dist/standalone/native-gateway.d.ts

@@ -8,6 +8,10 @@ type Target = {
 export declare const NATIVE_GATEWAY_CONFIG = "sso/native-nginx.conf";
 export declare function nativeGatewaySdk(sdk: string): boolean;
 export declare function nativeGatewaySupported(m: Target): boolean;
+/** Observe the boundary before DSM acquires web-config, without claiming port ownership. */
+export declare function renderNativeGatewayDiagnostic(m: Target, hook: string): string;
+/** Give a retiring nginx listener a bounded window before DSM acquires web-config. */
+export declare function renderNativeGatewayPortWait(m: Target, hook: string): string;
 export declare function gatewayEntryPath(m: Target): string;
 export declare function legacyGatewayNotice(): string;
 export declare function nativeGatewayResource(m: Target): Record<string, unknown> | undefined;

package/dist/standalone/native-gateway.js

@@ -10,6 +10,92 @@ export function nativeGatewaySupported(m) {
     return Boolean(m.identityGateway && nativeGatewaySdk(m.identityGateway.sdk)
         && m.os_min_ver && isDsmAtLeast(m.os_min_ver, PORTAL_MIN_DSM));
 }
+/** Observe the boundary before DSM acquires web-config, without claiming port ownership. */
+export function renderNativeGatewayDiagnostic(m, hook) {
+    if (!nativeGatewaySupported(m) || !['start-stop-status', 'postinst', 'postupgrade', 'preupgrade', 'preuninst'].includes(hook))
+        return '';
+    const ports = [...new Set([m.identityGateway.listen.https, m.identityGateway.listen.http].filter((port) => port !== undefined))];
+    const action = hook === 'start-stop-status'
+        ? `  case "\${1:-}" in prestart|prestop|start|stop|restart) action="$1" ;; *) exit 0 ;; esac\n`
+        : '  action=hook\n';
+    // Only fixed phase names and declared public ports reach syslog. In particular,
+    // never log argv, environment dumps, request/session data or a guessed owner.
+    return `synopkgland_native_diagnostic() (
+  command -v logger >/dev/null 2>&1 || exit 0
+${action}  case "\${SYNOPKG_PKG_STATUS:-}" in
+    INSTALL|UPGRADE|UNINSTALL|START|STOP) reason="$SYNOPKG_PKG_STATUS" ;;
+    '') reason=NONE ;;
+    *) reason=UNKNOWN ;;
+  esac
+  stamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ') || stamp=unknown
+  socket_state() {
+    if [ ! -r "$1" ]; then echo unknown; return; fi
+    awk -v port="$2" '$4 == "0A" && toupper($2) ~ (":" port "$") { found=1 } END { print found ? "listening" : "clear" }' "$1" || echo unknown
+  }
+${ports.map(port => `  tcp4=$(socket_state /proc/net/tcp ${port.toString(16).toUpperCase().padStart(4, '0')})
+  tcp6=$(socket_state /proc/net/tcp6 ${port.toString(16).toUpperCase().padStart(4, '0')})
+  logger -p user.warning -t synopkgland "NATIVE_GATEWAY_LIFECYCLE at=$stamp package=${m.package} hook=${hook} action=$action reason=$reason port=${port} tcp4=$tcp4 tcp6=$tcp6" || :
+`).join('')})
+synopkgland_native_diagnostic "$@" >/dev/null 2>&1 || :
+`;
+}
+/** Give a retiring nginx listener a bounded window before DSM acquires web-config. */
+export function renderNativeGatewayPortWait(m, hook) {
+    if (hook !== 'start-stop-status' || !nativeGatewaySupported(m))
+        return '';
+    const ports = [...new Set([m.identityGateway.listen.https, m.identityGateway.listen.http].filter((port) => port !== undefined))];
+    return `synopkgland_native_port_wait() (
+  [ "\${1:-}" = prestart ] || exit 0
+  socket_state() {
+    if [ ! -r "$1" ]; then echo unknown; return; fi
+    awk -v port="$2" '$4 == "0A" && toupper($2) ~ (":" port "$") { found=1 } END { print found ? "listening" : "clear" }' "$1" || echo unknown
+  }
+  remaining=30
+  polls=0
+  monotonic_cs() {
+    read uptime unused < /proc/uptime || return 1
+    whole=\${uptime%.*}
+    fraction=\${uptime#*.}
+    case "$whole" in ''|*[!0-9]*) return 1 ;; esac
+    case "$fraction" in [0-9][0-9]) : ;; *) return 1 ;; esac
+    echo $((whole * 100 + 1$fraction - 100))
+  }
+  started=$(monotonic_cs) || started=
+  deadline=$((\${started:-0} + 1500))
+  while :; do
+    busy=0
+    unknown=0
+    for port in ${ports.map(port => port.toString(16).toUpperCase().padStart(4, '0')).join(' ')}; do
+      for table in /proc/net/tcp /proc/net/tcp6; do
+        case "$(socket_state "$table" "$port")" in
+          listening) busy=1 ;;
+          clear) : ;;
+          *) unknown=1 ;;
+        esac
+      done
+    done
+    if [ "$busy" -eq 0 ]; then
+      outcome=clear
+      [ "$unknown" -eq 0 ] || outcome=unknown
+      break
+    fi
+    if [ "$remaining" -eq 0 ]; then outcome=timeout; break; fi
+    now=$(monotonic_cs) || now=
+    if [ -z "$started" ] || [ -z "$now" ]; then outcome=unavailable; break; fi
+    left=$((deadline - now))
+    if [ "$left" -le 0 ]; then outcome=timeout; break; fi
+    delay=0.5
+    if [ "$left" -lt 50 ]; then delay=$(printf '0.%02d' "$left"); fi
+    sleep "$delay" || { outcome=unavailable; break; }
+    remaining=$((remaining - 1))
+    polls=$((polls + 1))
+  done
+  stamp=$(date -u '+%Y-%m-%dT%H:%M:%SZ') || stamp=unknown
+  logger -p user.warning -t synopkgland "NATIVE_GATEWAY_PORT_WAIT at=$stamp package=${m.package} action=prestart ports=${ports.join(',')} outcome=$outcome polls=$polls" || :
+)
+synopkgland_native_port_wait "$@" >/dev/null 2>&1 || :
+`;
+}
 export function gatewayEntryPath(m) {
     return `/webman/3rdparty/${m.package}/sso/open.${m.identityGateway && !nativeGatewaySdk(m.identityGateway.sdk) ? 'html' : 'cgi'}`;
 }

package/package.json

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

package/skills/reference/diagnose.md

@@ -5,3 +5,51 @@ Start with check; inspect the built SPK. For DSM broken / 150 inspect Package Ce
 The independent container path uses resource-worker lifecycle. Unsupported Compose settings fail before build; there is no alternate installer. COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN means DSM may strip quoting from 純數字 command 元素. Use a single shell command when appropriate, for example `command: ["sh","-c","httpd -f -p 18333 -h /srv"]`.
 
 Never work around a failed permission check by running the package as root. Native CGI authentication and root-operation administrator approval are separate checks.
+
+## Native HTTPS fails before the App starts
+
+For a package using DSM-managed native gateway HTTPS (including Compose Apps),
+`start_failed` can occur after `start-stop-status prestart` succeeds but before
+DSM invokes `start`. Check `/var/log/packages/<package>.log`,
+`/var/log/synopkg.log`, `/var/log/synopkgmgr.log` and `/var/log/messages` at the
+same timestamp. `Failed to acquire startup worker` (272) plus
+`Runtime port <port> conflict for nginx` identifies the DSM `web-config` resource
+boundary. Increasing the daemon or Compose startup timeout cannot repair a
+failure that occurs before the daemon controller runs.
+
+New builds emit `NATIVE_GATEWAY_LIFECYCLE` records to local syslog at SDK hook entry
+for prestart, prestop, start, stop, restart and the install/upgrade/removal hooks.
+The record contains a UTC timestamp, package, fixed hook/action/reason, declared
+public port, and IPv4/IPv6 TCP listener presence from `/proc/net/tcp{,6}`:
+`listening`, `clear`, or `unknown`. It records no usernames, environment dumps,
+credentials or application arguments. Records use `user.warning` because DSM
+may filter notice-level messages; these records are observations, not error verdicts. Status polls are silent. Missing logger or
+unreadable proc data does not change the lifecycle result.
+
+Before the existing SDK and App prestart steps, native gateway builds also
+check all declared public ports for IPv4/IPv6 TCP listeners. While any is
+listening, one shared monotonic 15-second deadline includes probe time, with at
+most thirty sleeps of up to 0.5 seconds. The final sleep uses only the remaining
+budget; scheduling and the final local probe can add slight overhead. No listener
+means no sleep. Unknown
+probe results do not themselves trigger a wait. `NATIVE_GATEWAY_PORT_WAIT`
+records the outcome (`clear`, `timeout`, `unknown`, or `unavailable`) and the
+number of sleeps. Timeout, logger failure, or an unavailable sleep command
+continues to the original prestart steps and preserves their exit semantics;
+DSM remains responsible for acquiring the resource and reporting a conflict.
+This is an observation-only mitigation, without signalling processes or a root
+helper. Inspect accepts the exact current scripts, the prior diagnostic-only
+scripts, and the original released scripts; edited waits or SDK steps fail.
+
+These observations do not identify the listener's owner or reserve the port.
+They do not prove that a listener persisted until DSM's subsequent resource
+check, and a missing record may mean logging was unavailable. Correlate them
+with DSM's own hook begin/end records. During an authorized reproduction, also
+capture a timestamped `netstat -lntp` (administrator access may be required),
+nginx process/config state, package state and daemon logs before attempting
+recovery. Keep system logs private and redact them before sharing. A later
+native Start success proves recovery, not why the previous attempt failed.
+
+Do not restart nginx, change DSM port assignments, kill unrelated listeners,
+or add automatic package-start retries to hide an unproven conflict. Rebuild
+an App to obtain the diagnostic hooks; existing installed packages are unchanged.