@synopackageland/cli 0.3.0 → 0.3.2

package/dist/build-spk/generator.js

@@ -5,7 +5,7 @@ import { createHash } from "node:crypto";
 import * as tar from "tar";
 import { loadContract, collectInstallParameters } from "../contract/load.js";
 import { renderDsmWindowConfig, resolvedWebLaunch, trustedAppEntryPath, } from "../contract/web-launch.js";
-import { loadCompose } from "../compose/analyze.js";
+import { classifyComposeRoute, loadCompose } from "../compose/analyze.js";
 import { scanComposePrivilege } from "../compose/privilege.js";
 import { validateProject } from "../validate.js";
 import { writeDsmWindowIcons, writePackageCenterIcons } from "./dsm-icons.js";
@@ -16,6 +16,7 @@ import { BROKER_INSTALLER_VARS, BROKER_SOCKET_REQUIRED_SCRIPT, renderBrokerStatu
 import { loadNative } from "../native/load.js";
 import { materializeNativePayload } from "./native-payload.js";
 import { renderNativePrivilege, renderNativeStartStopStatus, renderNativePostuninst, } from "./native-lifecycle.js";
+import { renderResourceConfig, renderResourceWorkerStartStopStatus } from "./resource-worker.js";
 const FILE_MODE = 0o644;
 const SCRIPT_MODE = 0o755;
 const INSTALL_UIFILE = "install_uifile";
@@ -129,30 +130,56 @@ export async function buildSpk(options) {
             rmSync(staging, { recursive: true, force: true });
         }
     }
+    const parsedCompose = loadCompose(options.project.composePath);
+    const route = parsedCompose?.compose
+        ? classifyComposeRoute(contract, parsedCompose)
+        : undefined;
+    if (route && route.errors.length > 0) {
+        return { ok: false, errors: route.errors.map((error) => error.code) };
+    }
+    const rwEligibility = route?.eligibility;
+    const isDynamicRoute = route?.route === "dynamic" &&
+        rwEligibility?.adminport !== undefined &&
+        collectInstallParameters(contract).length > 0;
+    const isResourceWorkerRoute = route?.route === "static-zero-config" ||
+        isDynamicRoute;
     const staging = mkdtempSync(join(tmpdir(), "syno-spk-"));
     try {
-        writeFileSync(join(staging, "INFO"), renderInfo(contract, options.archFamily), "utf8");
+        writeFileSync(join(staging, "INFO"), renderInfo(contract, options.archFamily, isResourceWorkerRoute), "utf8");
         writePackageCenterIcons(staging);
         mkdirSync(join(staging, "conf"), { recursive: true });
         writeFileSync(join(staging, "conf", "privilege"), renderPrivilege(), "utf8");
         writeFileSync(join(staging, "privilege"), renderPrivilege(), "utf8");
+        if (isResourceWorkerRoute) {
+            const resourceConfig = renderResourceConfig(contract, rwEligibility);
+            writeFileSync(join(staging, "conf", "resource"), resourceConfig, "utf8");
+            chmodSync(join(staging, "conf", "resource"), FILE_MODE);
+        }
         mkdirSync(join(staging, "WIZARD_UIFILES"), { recursive: true });
-        const parsedCompose = loadCompose(options.project.composePath);
         writeFileSync(join(staging, "WIZARD_UIFILES", INSTALL_UIFILE), JSON.stringify(renderInstallWizard(contract, parsedCompose?.compose), null, 2), "utf8");
         writeFileSync(join(staging, "WIZARD_UIFILES", UPGRADE_UIFILE), JSON.stringify(renderUpgradeWizard(contract, parsedCompose?.compose), null, 2), "utf8");
         writeFileSync(join(staging, "WIZARD_UIFILES", UNINSTALL_UIFILE), JSON.stringify(renderUninstallWizard(), null, 2), "utf8");
         mkdirSync(join(staging, "scripts"), { recursive: true });
         for (const name of SCRIPT_NAMES) {
             const scriptPath = join(staging, "scripts", name);
-            writeFileSync(scriptPath, renderManagedScript(name, contract), "utf8");
+            writeFileSync(scriptPath, renderManagedScript(name, contract, undefined, isResourceWorkerRoute, rwEligibility?.adminport, isDynamicRoute), "utf8");
             chmodSync(scriptPath, SCRIPT_MODE);
         }
         mkdirSync(join(staging, "package"), { recursive: true });
         copyFileSync(options.project.composePath, join(staging, "package", "compose.yaml"));
         copyFileSync(options.project.contractPath, join(staging, "package", "synology-app.yaml"));
+        if (isResourceWorkerRoute) {
+            const resourceProjectDir = join(staging, "package", "compose");
+            mkdirSync(resourceProjectDir, { recursive: true });
+            copyFileSync(options.project.composePath, join(resourceProjectDir, "docker-compose.yml"));
+            chmodSync(join(resourceProjectDir, "docker-compose.yml"), FILE_MODE);
+        }
         const htmlDir = join(options.project.root, "html");
         if (existsSync(htmlDir)) {
             cpSync(htmlDir, join(staging, "package", "html"), { recursive: true });
+            if (isResourceWorkerRoute) {
+                cpSync(htmlDir, join(staging, "package", "compose", "html"), { recursive: true });
+            }
         }
         if (options.embeddedAttestationToken !== undefined) {
             const attestationPath = join(staging, "package", EMBEDDED_ATTESTATION_RELATIVE_PATH);
@@ -190,7 +217,7 @@ function quoteInfo(value) {
 function spkVersion(version) {
     return /-\d+$/.test(version) ? version : `${version}-0001`;
 }
-function renderInfo(contract, archFamily) {
+function renderInfo(contract, archFamily, isResourceWorker = false) {
     const lines = [];
     const add = (key, value) => {
         lines.push(`${key}=${quoteInfo(String(value))}`);
@@ -202,10 +229,22 @@ function renderInfo(contract, archFamily) {
     add("maintainer", String(contract.maintainer));
     add("arch", archFamily === undefined ? "noarch" : infoArchValue(archFamily));
     add("os_min_ver", String(contract.os_min_ver));
-    // synopkg's Container Manager dep gate reports "not ready" even when CM is
-    // running. Depend on Broker only; Broker's adapter.probe() checks CM at
-    // App install time (CM_CAPABILITY_MISSING).
-    add("install_dep_packages", "SynoPkgLandService>=0.1.0-0016");
+    if (isResourceWorker) {
+        // DSM reports Container Manager as "not ready" through the package
+        // dependency gate even while pkgctl-ContainerManager is running. The
+        // docker-project worker itself remains the authoritative live prerequisite
+        // (ContainerManager >= 1432); keep only the reliable Web Station package
+        // dependency here so a valid resource-worker SPK can reach acquisition.
+        if (contract.adminport !== undefined) {
+            add("install_dep_packages", "WebStation");
+        }
+    }
+    else {
+        // synopkg's Container Manager dep gate reports "not ready" even when CM is
+        // running. Depend on Broker only; Broker's adapter.probe() checks CM at
+        // App install time (CM_CAPABILITY_MISSING).
+        add("install_dep_packages", "SynoPkgLandService>=0.1.0-0016");
+    }
     add("startable", "yes");
     const launch = resolvedWebLaunch(contract);
     if (contract.adminprotocol) {
@@ -243,6 +282,7 @@ function renderPrivilege() {
     }, null, 2)}\n`;
 }
 const SHARED_FOLDER_MOUNT_CONSENT = "此 App 會用你在這台 NAS 選的資料夾；整顆應用都看得到。Shared Folder Mount 是整個 App Instance 的 container access：能打開這個 App 的使用者，容器裡的程式都看得到該 Share，即使該使用者在 File Station 看不到。這不是逐使用者 DSM ACL。要依登入者權限讀寫 NAS 檔案，必須另外核准廣域 files.* 並走 File Gateway。";
+const HOMES_MOUNT_CONSENT = "此 App 會使用這台 NAS 已啟用的 User Home；整顆應用的容器都看得到，容器路徑由 Compose 決定。這不是逐使用者 DSM ACL；要依登入者權限讀寫 NAS 檔案，必須另外核准廣域 files.* 並走 File Gateway。";
 const DSM_USER_RUN_AS_CONSENT = "寫進 Share 的新檔在 File Station 顯示為你選的那位 DSM 使用者。點開此 App 的人共用這個磁碟身分，不是逐登入 ACL。";
 const DSM_USER_UPGRADE_CONSENT = "升級時更換 Container Run-as 不會 chown Share 上的舊檔；只有升級後寫入的新檔才會使用新的磁碟身分。";
 const SHARED_FOLDER_RW_UPGRADE_CONSENT = "此版本把 Share 掛載改為讀寫；容器可讀取並寫入你選的 Share，不再是唯讀。";
@@ -315,11 +355,12 @@ function volumeMounts(compose) {
     }
     return mounts;
 }
+// A Compose that mounts nothing reaches even less of the NAS than one that
+// mounts only PKGVAR, so it earns the same consent line. Returning false for
+// zero sources left the wizard step with no items at all, and DSM's Package
+// Center rejects that SPK with "Invalid file format".
 function composeUsesOnlyAppSpace(compose) {
     const sources = volumeSources(compose);
-    if (sources.length === 0) {
-        return false;
-    }
     return sources.every((source) => source.startsWith("${SYNOPKG_PKGVAR}") || source.startsWith("${SYNO_APP_SECRETS_DIR}"));
 }
 const PRIVILEGE_MAX_WARNING = "此 App 的容器有高權限，接近這台 NAS 的 root、幾乎整台機器。是否安裝由你這位管理員決定。";
@@ -327,6 +368,7 @@ function renderInstallWizard(contract, compose) {
     const items = [];
     const params = collectInstallParameters(contract);
     const hasSharedFolder = params.some((item) => item.param.type === "shared_folder");
+    const hasHomes = params.some((item) => item.param.type === "homes");
     const hasDsmUser = params.some((item) => item.param.type === "dsm_user");
     const capabilityText = renderFilesCapability(contract);
     if (compose && scanComposePrivilege(compose).length > 0) {
@@ -344,6 +386,11 @@ function renderInstallWizard(contract, compose) {
             desc: SHARED_FOLDER_MOUNT_CONSENT,
         });
     }
+    if (hasHomes) {
+        items.push({
+            desc: HOMES_MOUNT_CONSENT,
+        });
+    }
     if (hasDsmUser) {
         items.push({
             desc: DSM_USER_RUN_AS_CONSENT,
@@ -354,7 +401,10 @@ function renderInstallWizard(contract, compose) {
             desc: capabilityText,
         });
     }
-    if (!hasSharedFolder && !capabilityText && compose && composeUsesOnlyAppSpace(compose)) {
+    // No compose at all is the native branch: the binary gets PKGVAR and nothing
+    // else, so it earns the same line. Requiring a compose left native wizards
+    // empty, which DSM rejects as an invalid package.
+    if (!hasSharedFolder && !capabilityText && (!compose || composeUsesOnlyAppSpace(compose))) {
         items.push({
             desc: APP_OWN_SPACE_CONSENT,
         });
@@ -511,7 +561,128 @@ function renderUninstallWizard() {
             ],
         }];
 }
-function renderManagedScript(name, contract, nativeContext) {
+function renderDynamicPreinstMaterializer(contract) {
+    const params = collectInstallParameters(contract).filter(({ param }) => param.type === "string" || param.type === "boolean");
+    const lines = [
+        "#!/bin/sh",
+        "set -eu",
+        "umask 077",
+        "# D3 package-only carrier; values are wizard answers, canonical values, or defaults.",
+        "die() { echo \"dynamic route materialization failed: $1\" >&2; exit 1; }",
+        'T="${SYNOPKG_PKGINST_TEMP_DIR:?}"',
+        'STATUS="${SYNOPKG_PKG_STATUS:?}"',
+        'PROJECT="$T/compose"',
+        'RUNTIME_ENV="$PROJECT/.env"',
+        'CANONICAL_ENV="${SYNOPKG_PKGDEST_VOL:?}/@appdata/${SYNOPKG_PKGNAME:?}/.env"',
+        'PLATFORM_PKGVAR="${SYNOPKG_PKGDEST_VOL:?}/@appdata/${SYNOPKG_PKGNAME:?}"',
+        'PLATFORM_SECRETS="${SYNOPKG_PKGDEST_VOL:?}/@apphome/${SYNOPKG_PKGNAME:?}/secrets"',
+        '[ -d "$PROJECT" ] || die "compose directory is missing"',
+        '[ ! -L "$PROJECT" ] || die "compose directory is a symlink"',
+        '[ "$(stat -c %u "$PROJECT")" = "$(id -u)" ] || die "compose directory owner is not the package user"',
+        '[ ! -L "$RUNTIME_ENV" ] || die "runtime file is a symlink"',
+        'if [ -e "$RUNTIME_ENV" ] && [ ! -f "$RUNTIME_ENV" ]; then die "runtime path is not a regular file"; fi',
+        "read_env_value() {",
+        "  file=\"$1\"",
+        "  key=\"$2\"",
+        "  awk -F= -v key=\"$key\" '$1 == key { value=substr($0, index($0,\"=\")+1); if (value ~ /^\".*\"$/) value=substr(value,2,length(value)-2); print value; found=1; exit } END { if (!found) exit 1 }' \"$file\"",
+        "}",
+        "append_env() {",
+        "  key=\"$1\"",
+        "  value=\"$2\"",
+        "  type=\"${3:-string}\"",
+        "  if printf '%s' \"$value\" | LC_ALL=C grep -q '[[:cntrl:]]'; then",
+        "    die \"control character in environment value $key\"",
+        "  fi",
+        "  case \"$value\" in",
+        "    *[[:cntrl:]]*) die \"control character in environment value $key\" ;;",
+        "  esac",
+        "  if [ \"$type\" = \"boolean\" ]; then",
+        "    normalized=\"$(printf '%s' \"$value\" | LC_ALL=C tr '[:upper:]' '[:lower:]')\"",
+        "    case \"$normalized\" in",
+        "      true|false) value=\"$normalized\" ;;",
+        "      *) die \"invalid boolean value $key\" ;;",
+        "    esac",
+        "  fi",
+        "  case \"$value\" in",
+        "    *[!A-Za-z0-9_./:@-]*)",
+        "      escaped=\"$(printf '%s' \"$value\" | sed 's/\\\\/\\\\\\\\/g; s/\"/\\\\\"/g')\"",
+        "      printf '%s=\"%s\"\\n' \"$key\" \"$escaped\"",
+        "      ;;",
+        "    *) printf '%s=%s\\n' \"$key\" \"$value\" ;;",
+        "  esac",
+        "}",
+        'tmp="$(mktemp "$PROJECT/.env.tmp.XXXXXX")"',
+        'chmod 600 "$tmp"',
+        '[ "$(stat -c %a "$tmp")" = "600" ] || die "temporary env mode is not 0600"',
+        '[ "$(stat -c %u "$tmp")" = "$(id -u)" ] || die "temporary env owner is not the package user"',
+        "trap 'rm -f \"$tmp\"' EXIT HUP INT TERM",
+        "{",
+    ];
+    const valueVars = [];
+    for (const { name, param } of params) {
+        const type = param.type;
+        const valueVar = "D3_VALUE_" + name;
+        valueVars.push({ name, valueVar, type });
+        const fallback = param.default !== undefined
+            ? String(param.default)
+            : type === "boolean"
+                ? "false"
+                : "";
+        lines.push(`  if [ "\${${name}+x}" = x ]; then`, `    ${valueVar}="\${${name}}"`, '  elif [ "$STATUS" = "UPGRADE" ] && [ -f "$CANONICAL_ENV" ] && [ ! -L "$CANONICAL_ENV" ] && ' +
+            `${valueVar}="$(read_env_value "$CANONICAL_ENV" "${name}")"; then`, "    :", "  else", "    " + valueVar + "=" + shellQuote(fallback), "  fi");
+    }
+    lines.push('  append_env "SYNOPKG_PKGVAR" "$PLATFORM_PKGVAR"', '  append_env "SYNO_APP_SECRETS_DIR" "$PLATFORM_SECRETS"');
+    for (const { name, valueVar, type } of valueVars) {
+        lines.push(`  append_env "${name}" "$${valueVar}" "${type}"`);
+    }
+    lines.push("  } > \"$tmp\"", "  mv \"$tmp\" \"$RUNTIME_ENV\"", "  trap - EXIT HUP INT TERM", "  [ ! -L \"$RUNTIME_ENV\" ] || die \"runtime file became a symlink\"", "  [ \"$(stat -c %a \"$RUNTIME_ENV\")\" = \"600\" ] || die \"runtime env mode is not 0600\"", "exit 0");
+    return lines.join("\n") + "\n";
+}
+function renderDynamicCanonicalMirror() {
+    const lines = [
+        "#!/bin/sh",
+        "set -eu",
+        "umask 077",
+        "# D3 post-worker mirror; the runtime .env is the only source of truth here.",
+        "die() { echo \"dynamic route canonical mirror failed: $1\" >&2; exit 1; }",
+        'PKGVAR="${SYNOPKG_PKGVAR:?}"',
+        'PKGHOME="${SYNOPKG_PKGHOME:?}"',
+        'PKGDEST="${SYNOPKG_PKGDEST:?}"',
+        'PROJECT="${PKGDEST}/compose"',
+        'RUNTIME_ENV="${PROJECT}/.env"',
+        'CANONICAL_ENV="${PKGVAR}/.env"',
+        'SECRETS="${PKGHOME}/secrets"',
+        'mkdir -p "$PKGVAR"',
+        '[ -d "$PKGVAR" ] || die "PKGVAR is not a directory"',
+        'if [ -L "$SECRETS" ]; then die "secret root is a symlink"; fi',
+        'mkdir -p "$SECRETS"',
+        '[ -d "$SECRETS" ] || die "secret root is not a directory"',
+        'chmod 700 "$SECRETS"',
+        '[ "$(stat -c %a "$SECRETS")" = "700" ] || die "secret root mode is not 0700"',
+        '[ -d "$PROJECT" ] || die "project directory is missing"',
+        '[ ! -L "$PROJECT" ] || die "project directory is a symlink"',
+        '[ ! -L "$RUNTIME_ENV" ] || die "runtime file is a symlink"',
+        '[ -f "$RUNTIME_ENV" ] || die "runtime file is not a regular file"',
+        '[ ! -L "$CANONICAL_ENV" ] || die "canonical file is a symlink"',
+        'if [ -e "$CANONICAL_ENV" ] && [ ! -f "$CANONICAL_ENV" ]; then die "canonical path is not a regular file"; fi',
+        'tmp="$(mktemp "$PKGVAR/.env.tmp.XXXXXX")"',
+        'chmod 600 "$tmp"',
+        '[ "$(stat -c %a "$tmp")" = "600" ] || die "temporary env mode is not 0600"',
+        'trap \'rm -f "$tmp"\' EXIT HUP INT TERM',
+        'cp "$RUNTIME_ENV" "$tmp"',
+        'chmod 600 "$tmp"',
+        'mv "$tmp" "$CANONICAL_ENV"',
+        'trap - EXIT HUP INT TERM',
+        '[ ! -L "$CANONICAL_ENV" ] || die "canonical file became a symlink"',
+        '[ "$(stat -c %a "$CANONICAL_ENV")" = "600" ] || die "canonical env mode is not 0600"',
+        "exit 0",
+    ];
+    return lines.join("\n") + "\n";
+}
+function shellQuote(value) {
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+function renderManagedScript(name, contract, nativeContext, isResourceWorker = false, resourceWorkerAdminport, isDynamicRoute = false) {
     if (nativeContext) {
         const lifecycleInput = {
             packageIdentity: String(contract.package),
@@ -549,6 +720,31 @@ fi
         }
         return `#!/bin/sh\nexit 0\n`;
     }
+    if (isResourceWorker) {
+        if (name === "start-stop-status") {
+            return renderResourceWorkerStartStopStatus(resourceWorkerAdminport);
+        }
+        if (isDynamicRoute && name === "preinst") {
+            return renderDynamicPreinstMaterializer(contract);
+        }
+        if (isDynamicRoute && (name === "postinst" || name === "postupgrade")) {
+            return renderDynamicCanonicalMirror();
+        }
+        if (name === "postuninst") {
+            const projectRoot = isDynamicRoute ? 'PROJECT="${SYNOPKG_PKGDEST}/compose"\n' : "";
+            const deleteRoots = isDynamicRoute
+                ? ["PKGVAR", "PROJECT", "SECRETS"]
+                : ["PKGVAR", "SECRETS"];
+            return `#!/bin/sh
+set -eu
+PKGVAR="\${SYNOPKG_PKGVAR}"
+PKGHOME="\${SYNOPKG_PKGHOME}"
+SECRETS="\${PKGHOME}/secrets"
+${projectRoot}${renderDeleteAppDataBlock(deleteRoots)}exit 0
+`;
+        }
+        return `#!/bin/sh\nexit 0\n`;
+    }
     if (name === "start-stop-status") {
         return `#!/bin/sh
 ${BROKER_INSTALLER_VARS}

package/dist/build-spk/resource-worker.d.ts

@@ -0,0 +1,14 @@
+import type { AppContract } from "../types.js";
+import type { ResourceWorkerEligibility } from "../compose/analyze.js";
+export { classifyComposeRoute, resourceWorkerEligibility, type ComposeRoute, type ComposeRouteClassification, type ResourceWorkerEligibility, type ResourceWorkerIneligibleReason, } from "../compose/analyze.js";
+export declare function composeProjectName(packageId: string): string;
+export declare function renderDockerProjectResource(packageId: string, projectPath?: string): Record<string, unknown>;
+export declare function renderWebserviceResource(contract: AppContract, adminport: number): Record<string, unknown>;
+export declare function renderResourceConfig(contract: AppContract, eligibility: ResourceWorkerEligibility): string;
+/**
+ * Renders the lifecycle control script for the Docker Project resource-worker
+ * route. ContainerManager owns the actual project start/stop operation through
+ * the worker timing hooks; the package script must wait for that operation to
+ * leave a reachable service and must not claim running unconditionally.
+ */
+export declare function renderResourceWorkerStartStopStatus(adminport?: number): string;

package/dist/build-spk/resource-worker.js

@@ -0,0 +1,140 @@
+import { cookieStripHeaders, resolvedWebLaunch, webStationAlias, webStationServiceName, } from "../contract/web-launch.js";
+export { classifyComposeRoute, resourceWorkerEligibility, } from "../compose/analyze.js";
+export function composeProjectName(packageId) {
+    const slug = packageId
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^[-_]+|[-_]+$/g, "");
+    return slug.length > 0 ? slug : "app";
+}
+export function renderDockerProjectResource(packageId, projectPath = "compose") {
+    const projectName = composeProjectName(packageId);
+    return {
+        "docker-project": {
+            projects: [
+                {
+                    name: projectName,
+                    path: projectPath,
+                    build_params: {
+                        force_pull: true,
+                        force_recreate: true,
+                        build: false,
+                    },
+                },
+            ],
+        },
+    };
+}
+export function renderWebserviceResource(contract, adminport) {
+    const alias = webStationAlias(String(contract.package));
+    const launch = resolvedWebLaunch(contract);
+    const cookieHeaders = cookieStripHeaders(contract);
+    const proxyHeaderEntries = cookieHeaders.map((header) => ({
+        name: header.name,
+        value: header.value,
+    }));
+    const service = {
+        service: webStationServiceName(alias),
+        display_name: String(contract.displayname ?? contract.package),
+        type: "reverse_proxy",
+        support_alias: true,
+        support_server: false,
+        proxy_target: `http://127.0.0.1:${adminport}`,
+        proxy_headers: proxyHeaderEntries,
+    };
+    const portal = {
+        service: webStationServiceName(alias),
+        name: alias,
+        type: "alias",
+        alias,
+    };
+    if (launch === "dsm-window") {
+        portal.app = String(contract.package);
+    }
+    return {
+        webservice: {
+            services: [service],
+            portals: [portal],
+        },
+    };
+}
+export function renderResourceConfig(contract, eligibility) {
+    const packageId = String(contract.package);
+    const dockerResource = renderDockerProjectResource(packageId, "compose");
+    let combined = { ...dockerResource };
+    if (eligibility.adminport !== undefined) {
+        const webResource = renderWebserviceResource(contract, eligibility.adminport);
+        combined = {
+            ...combined,
+            ...webResource,
+        };
+    }
+    return `${JSON.stringify(combined, null, 2)}\n`;
+}
+/**
+ * Renders the lifecycle control script for the Docker Project resource-worker
+ * route. ContainerManager owns the actual project start/stop operation through
+ * the worker timing hooks; the package script must wait for that operation to
+ * leave a reachable service and must not claim running unconditionally.
+ */
+export function renderResourceWorkerStartStopStatus(adminport) {
+    if (adminport === undefined) {
+        return `#!/bin/sh
+case "$1" in
+  start|status)
+    echo "resource-worker package has no published port to probe" >&2
+    exit 3
+    ;;
+  stop) exit 0 ;;
+  *) exit 1 ;;
+esac
+`;
+    }
+    const url = `http://127.0.0.1:${adminport}/`;
+    return `#!/bin/sh
+probe_service() {
+  if command -v curl >/dev/null 2>&1; then
+    curl --silent --output /dev/null --connect-timeout 2 --max-time 5 "${url}"
+    return $?
+  fi
+  if command -v wget >/dev/null 2>&1; then
+    wget --quiet --output-document=/dev/null --timeout=5 --tries=1 "${url}"
+    return $?
+  fi
+  return 127
+}
+
+wait_for_service() {
+  attempts=0
+  while [ "$attempts" -lt 30 ]; do
+    if probe_service; then
+      return 0
+    fi
+    attempts=$((attempts + 1))
+    sleep 1
+  done
+  return 1
+}
+
+case "$1" in
+  start)
+    if wait_for_service; then
+      exit 0
+    fi
+    exit 3
+    ;;
+  stop)
+    exit 0
+    ;;
+  status)
+    if probe_service; then
+      exit 0
+    fi
+    exit 3
+    ;;
+  *)
+    exit 1
+    ;;
+esac
+`;
+}

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { resolve, dirname } from "node:path";
 import { findProjectRoot } from "./discovery.js";
+import { loadContract } from "./contract/load.js";
 import { formatErrors } from "./errors.js";
 import { formatInspectReport, inspectProject } from "./inspect.js";
 import { initFromTemplate, isTemplateName, listTemplates } from "./init.js";
@@ -19,6 +20,7 @@ import { publishProject, resolveCommunityAppsRoot } from "./publish/publish.js";
 import { formatPreflight, runPublicReleasePreflight } from "./publish/preflight.js";
 import { createExecGitHubCli, createExecGitOps } from "./publish/github-pr.js";
 import { communityAppsGitHubRepo } from "./publish/github-repo.js";
+import { resolveInstallParameterExtraValues } from "./deploy/param-values.js";
 function collectKvOption(value, previous, flag, example) {
     const separator = value.indexOf("=");
     if (separator <= 0) {
@@ -35,9 +37,15 @@ function collectShareOption(value, previous) {
 function collectRunAsOption(value, previous) {
     return collectKvOption(value, previous, "--run-as", "--run-as RUN_AS=alice");
 }
+function collectParamOption(value, previous) {
+    return collectKvOption(value, previous, "--param", "--param APP_MODE=prod");
+}
 function resolveProject(cwd, project) {
     const start = project ? resolve(cwd, project) : cwd;
-    const found = findProjectRoot(start);
+    return findProjectRoot(start);
+}
+function requireProject(cwd, project) {
+    const found = resolveProject(cwd, project);
     if (!found) {
         console.error("找不到 synology-app.yaml。請在專案根目錄執行，或使用 --project 指定。");
         process.exit(1);
@@ -50,12 +58,53 @@ export async function runCli(argv) {
         .name("synopkgland")
         .description("Syno Package Land Developer Kit CLI")
         .option("--project <dir>", "App 專案根目錄");
+    program
+        .command("doctor")
+        .description("唯讀診斷本機合約／Compose 與 NAS 部署狀態")
+        .option("--host <name>", "synoagentcli profile 或 NAS 名稱")
+        .option("--package <id>", "指定診斷的 Package Identity（省略時由合約判定）")
+        .option("--dev", "診斷 Development Package Identity（{package}.dev）")
+        .option("--json", "輸出 machine-readable JSON 診斷報告")
+        .action(async (options, command) => {
+        const global = command.parent?.opts() ?? {};
+        const project = resolveProject(process.cwd(), global.project);
+        let host = null;
+        if (options.host) {
+            host = createNasHost({ host: options.host });
+            if (!host) {
+                console.error(`[${"HOST_CREDENTIALS_MISSING"}] 找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。`);
+                process.exit(1);
+            }
+        }
+        try {
+            const { runDoctor, formatDoctorReport } = await import("./doctor.js");
+            const report = await runDoctor({
+                project,
+                host,
+                packageId: options.package,
+                dev: options.dev,
+            });
+            if (options.json) {
+                console.log(JSON.stringify(report, null, 2));
+            }
+            else {
+                console.log(formatDoctorReport(report));
+            }
+            if (!report.ok) {
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
     program
         .command("validate")
         .description("驗證 App Contract 與 Compose")
         .action((options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         const result = validateProject(project, {
             profile: "personal",
         });
@@ -73,7 +122,7 @@ export async function runCli(argv) {
         .description("檢視 Compose 意圖與 Web entry 提示")
         .action((_options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         const report = inspectProject(project);
         console.log(formatInspectReport(report));
     });
@@ -112,7 +161,7 @@ export async function runCli(argv) {
         .option("--files-root <dir>", "將本機目錄對應為 NAS Logical Path")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         const validation = validateProject(project);
         if (!validation.ok) {
             console.error(formatErrors(validation.errors));
@@ -146,7 +195,7 @@ export async function runCli(argv) {
         .option("--dev", "檢查 Development Package Identity（{package}.dev）")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         if (options.host) {
             const host = createNasHost({ host: options.host });
             if (!host) {
@@ -189,9 +238,18 @@ export async function runCli(argv) {
         .option("--replace-curated", "危險：將既有 Curated App Package Attestation 降級為 Local Attestation")
         .option("--share <slot=name>", "此 NAS 上的 Shared Folder 邏輯名（契約 shared_folder 槽，可重複）", collectShareOption)
         .option("--run-as <slot=name>", "此 NAS 上的 DSM 使用者邏輯名（契約 dsm_user 槽）", collectRunAsOption)
+        .option("--param <NAME=value>", "契約 string/boolean Install Parameter 答案（可重複）", collectParamOption)
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
+        const parameterCheck = resolveInstallParameterExtraValues({
+            contract: loadContract(project.contractPath).contract,
+            provided: options.param,
+        });
+        if (!parameterCheck.ok) {
+            console.error(`[${parameterCheck.code}] ${parameterCheck.message}`);
+            process.exit(1);
+        }
         const host = createNasHost({ host: options.host });
         if (!host) {
             console.error("找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
@@ -210,6 +268,7 @@ export async function runCli(argv) {
                 replaceCurated: options.replaceCurated,
                 shareValues: options.share,
                 runAsValues: options.runAs,
+                paramValues: options.param,
             });
             if (!result.ok) {
                 console.error(`[${result.code ?? "DEPLOY_FAILED"}] ${result.message ?? "部署失敗。"}`);
@@ -232,7 +291,7 @@ export async function runCli(argv) {
         .option("--dev", "查詢 Development Package Identity")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         const host = createNasHost({ host: options.host });
         if (!host) {
             console.error("找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
@@ -254,7 +313,7 @@ export async function runCli(argv) {
         .option("--dev", "查詢 Development Package Identity")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         const host = createNasHost({ host: options.host });
         if (!host) {
             console.error("找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
@@ -312,7 +371,7 @@ export async function runCli(argv) {
         .option("--arch <family>", "native App 的目標架構：x86_64 或 aarch64（Compose App 不需要）")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         if (options.arch !== undefined && !isNativeArchFamily(String(options.arch))) {
             console.error(`--arch 只接受 x86_64 或 aarch64，收到 ${String(options.arch)}。`);
             process.exit(1);
@@ -336,7 +395,7 @@ export async function runCli(argv) {
         .option("--base <branch>", "PR 目標分支", "master")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         const preflight = await runPublicReleasePreflight(project);
         if (!preflight.ok) {
             // A gate's reasons belong on stderr so CI logs and `2>` capture them.