@synopackageland/cli 0.3.3 → 0.3.5

package/dist/build-spk/generator.js

@@ -3,6 +3,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
 import * as tar from "tar";
+import { parseDocument, Scalar } from "yaml";
 import { loadContract, collectInstallParameters } from "../contract/load.js";
 import { renderDsmWindowConfig, resolvedWebLaunch, trustedAppEntryPath, } from "../contract/web-launch.js";
 import { classifyComposeRoute, loadCompose } from "../compose/analyze.js";
@@ -16,7 +17,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";
+import { renderHeadlessResourceMarker, renderResourceConfig, renderResourceWorkerStartStopStatus, } from "./resource-worker.js";
 const FILE_MODE = 0o644;
 const SCRIPT_MODE = 0o755;
 const INSTALL_UIFILE = "install_uifile";
@@ -160,7 +161,7 @@ export async function buildSpk(options) {
         mkdirSync(join(staging, "scripts"), { recursive: true });
         for (const name of SCRIPT_NAMES) {
             const scriptPath = join(staging, "scripts", name);
-            writeFileSync(scriptPath, renderManagedScript(name, contract, undefined, isResourceWorkerRoute, rwEligibility?.adminport, isDynamicRoute), "utf8");
+            writeFileSync(scriptPath, renderManagedScript(name, contract, undefined, isResourceWorkerRoute, rwEligibility?.adminport, isDynamicRoute, rwEligibility?.headless === true), "utf8");
             chmodSync(scriptPath, SCRIPT_MODE);
         }
         mkdirSync(join(staging, "package"), { recursive: true });
@@ -169,7 +170,27 @@ export async function buildSpk(options) {
         if (isResourceWorkerRoute) {
             const resourceProjectDir = join(staging, "package", "compose");
             mkdirSync(resourceProjectDir, { recursive: true });
-            copyFileSync(options.project.composePath, join(resourceProjectDir, "docker-compose.yml"));
+            const dsmUserParam = collectInstallParameters(contract).find((p) => p.param.type === "dsm_user");
+            if (dsmUserParam) {
+                const rawYaml = readFileSync(options.project.composePath, "utf8");
+                const doc = parseDocument(rawYaml);
+                const services = doc.get("services");
+                if (services && typeof services === "object" && typeof services.toJSON === "function") {
+                    const serviceNames = Object.keys(services.toJSON());
+                    for (const sName of serviceNames) {
+                        const userVal = new Scalar(`\${${dsmUserParam.name}_UID}:\${${dsmUserParam.name}_GID}`);
+                        userVal.type = Scalar.QUOTE_DOUBLE;
+                        doc.setIn(["services", sName, "user"], userVal);
+                    }
+                }
+                let composeContent = doc.toString();
+                const escaped = `\\$\\{${dsmUserParam.name}_UID\\}:\\$\\{${dsmUserParam.name}_GID\\}`;
+                composeContent = composeContent.replace(new RegExp(`^([ \\t]*)user:\\s*"${escaped}"`, "gm"), `$1user: "\${${dsmUserParam.name}_UID}:\${${dsmUserParam.name}_GID}"\n$1# synopkgland:group_add ${dsmUserParam.name}`);
+                writeFileSync(join(resourceProjectDir, "docker-compose.yml"), composeContent, "utf8");
+            }
+            else {
+                copyFileSync(options.project.composePath, join(resourceProjectDir, "docker-compose.yml"));
+            }
             chmodSync(join(resourceProjectDir, "docker-compose.yml"), FILE_MODE);
         }
         const htmlDir = join(options.project.root, "html");
@@ -559,14 +580,30 @@ function renderUninstallWizard() {
             ],
         }];
 }
+const LEGACY_BROKER_STATE_REGISTRY_CODE = "COMPOSE_LEGACY_BROKER_STATE_PRESENT";
 function renderDynamicPreinstMaterializer(contract) {
-    const params = collectInstallParameters(contract).filter(({ param }) => param.type === "string" || param.type === "boolean");
+    const allParams = collectInstallParameters(contract);
+    const scalarParams = allParams.filter(({ param }) => param.type === "string" || param.type === "boolean");
+    const sharedFolderParams = allParams.filter(({ param }) => param.type === "shared_folder");
+    const dsmUserParam = allParams.find(({ param }) => param.type === "dsm_user");
     const lines = [
         "#!/bin/sh",
         "set -eu",
         "umask 077",
-        "# D3 package-only carrier; values are wizard answers, canonical values, or defaults.",
+        "# D3/D5.4 package-only carrier; values are wizard answers, canonical values, or defaults.",
         "die() { echo \"dynamic route materialization failed: $1\" >&2; exit 1; }",
+        `# registry-code="${LEGACY_BROKER_STATE_REGISTRY_CODE}"`,
+        'APPDATA="${SYNOPKG_PKGDEST_VOL:?}/@appdata/${SYNOPKG_PKGNAME:?}"',
+        'if [ -d "$APPDATA" ]; then',
+        '  broker_uid="$(id -u SynoPkgLandService 2>/dev/null || true)"',
+        '  if [ -n "$broker_uid" ]; then',
+        '    for item in "$APPDATA"/* "$APPDATA"/.[!.]* "$APPDATA"/..?*; do',
+        '      [ -e "$item" ] || continue',
+        '      item_uid="$(stat -c %u "$item" 2>/dev/null || true)"',
+        '      [ "$item_uid" = "$broker_uid" ] && die "MIGRATION_UNSUPPORTED: ${SYNOPKG_PKGNAME} 曾由 Broker installer 安裝；dynamic 路線不支援就地遷移，請以新的 Package Identity 安裝或先完整卸載並清除 App Data"',
+        "    done",
+        "  fi",
+        "fi",
         'T="${SYNOPKG_PKGINST_TEMP_DIR:?}"',
         'STATUS="${SYNOPKG_PKG_STATUS:?}"',
         'PROJECT="$T/compose"',
@@ -609,15 +646,16 @@ function renderDynamicPreinstMaterializer(contract) {
         "    *) 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",
-        "{",
     ];
+    if (sharedFolderParams.length > 0) {
+        lines.push("resolve_shared_folder() {", "  share_name=\"$1\"", "  case \"$share_name\" in", "    */*|*..*) die \"invalid share name $share_name\" ;;", "    '') die \"share name is empty\" ;;", "  esac", "  mounts_file=\"${D54_MOUNTS_FILE:-/proc/mounts}\"", "  if [ ! -r \"$mounts_file\" ] && [ -r \"/etc/mtab\" ]; then", "    mounts_file=\"/etc/mtab\"", "  fi", "  if [ ! -r \"$mounts_file\" ]; then", "    die \"cannot read mount points from $mounts_file\"", "  fi", "  vols=\"$(awk '$2 ~ /^\\/volume[0-9]+$/ {print $2}' \"$mounts_file\" | sort -u)\"", '  if [ -z "$vols" ]; then', "    vols=\"$(awk '{print $2}' \"$mounts_file\" | sort -u)\"", "  fi", "  matched=\"\"", "  count=0", "  for v in $vols; do", "    if [ -d \"$v/$share_name\" ]; then", "      matched=\"$v/$share_name\"", "      count=$((count + 1))", "    fi", "  done", "  if [ \"$count\" -eq 0 ]; then", "    die \"share $share_name not found on any volume\"", "  elif [ \"$count\" -gt 1 ]; then", "    die \"share $share_name matched multiple volumes\"", "  fi", "  printf '%s' \"$matched\"", "}");
+    }
+    if (dsmUserParam) {
+        lines.push("resolve_dsm_user() {", "  user_name=\"$1\"", "  case \"$user_name\" in", "    */*|*..*|*[[:cntrl:]]*) die \"invalid user name $user_name\" ;;", "    '') die \"user name is empty\" ;;", "  esac", "  u_uid=\"$(id -u -- \"$user_name\" 2>/dev/null || true)\"", "  case \"$u_uid\" in", "    ''|*[!0-9]*) die \"resolved uid for $user_name is not a valid integer\" ;;", "    0) die \"resolved uid for $user_name cannot be 0 (root)\" ;;", "  esac", "  u_gid=\"$(id -g -- \"$user_name\" 2>/dev/null || true)\"", "  case \"$u_gid\" in", "    ''|*[!0-9]*) die \"resolved gid for $user_name is not a valid integer\" ;;", "  esac", "  # id -G returns all group ids including primary", "  raw_groups=\"$(id -G -- \"$user_name\" 2>/dev/null || true)\"", "  # filter out primary gid, deduplicate, keep numeric only", "  supp_groups=\"\"", "  for g in $raw_groups; do", "    case \"$g\" in", "      ''|*[!0-9]*) continue ;;", "    esac", "    if [ \"$g\" != \"$u_gid\" ]; then", "      already=0", "      for sg in $supp_groups; do", "        if [ \"$sg\" = \"$g\" ]; then", "          already=1", "          break", "        fi", "      done", "      if [ \"$already\" -eq 0 ]; then", "        supp_groups=\"${supp_groups}${supp_groups:+ }$g\"", "      fi", "    fi", "  done", "  printf '%s %s %s' \"$u_uid\" \"$u_gid\" \"$supp_groups\"", "}", "rewrite_group_add() {", "  p_name=\"$1\"", "  g_list=\"$2\"", "  compose_file=\"$3\"", "  [ -f \"$compose_file\" ] || die \"compose file missing at $compose_file\"", "  [ ! -L \"$compose_file\" ] || die \"compose file is a symlink\"", "  tmp_compose=\"$(mktemp \"${compose_file}.tmp.XXXXXX\")\"", "  awk -v param=\"$p_name\" -v g_list=\"$g_list\" '", "    BEGIN {", "      n = split(g_list, g_arr, \" \")", "    }", "    {", "      regex = \"^[ \\t]*# synopkgland:group_add \" param \"$\"", "      if ($0 ~ regex) {", "        match($0, /^[ \\t]*/)", "        indent = substr($0, RSTART, RLENGTH)", "        if (n > 0) {", "          print indent \"group_add:\"", "          for (i = 1; i <= n; i++) {", "            print indent \"  - ${\" param \"_GROUP_\" i \"}\"", "          }", "        }", "      } else {", "        print $0", "      }", "    }", "  ' \"$compose_file\" > \"$tmp_compose\" || die \"failed to rewrite group_add in $compose_file\"", "  mv \"$tmp_compose\" \"$compose_file\" || die \"failed to replace $compose_file\"", "}");
+    }
+    lines.push('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) {
+    for (const { name, param } of scalarParams) {
         const type = param.type;
         const valueVar = "D3_VALUE_" + name;
         valueVars.push({ name, valueVar, type });
@@ -629,14 +667,36 @@ function renderDynamicPreinstMaterializer(contract) {
         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");
     }
+    const shareVars = [];
+    for (const { name } of sharedFolderParams) {
+        const rawVar = "D54_RAW_SHARE_" + name;
+        const pathVar = "D54_RESOLVED_PATH_" + name;
+        shareVars.push({ name, pathVar });
+        lines.push(`  if [ "\${${name}+x}" = x ]; then`, `    ${rawVar}="\${${name}}"`, '  elif [ "$STATUS" = "UPGRADE" ] && [ -f "$CANONICAL_ENV" ] && [ ! -L "$CANONICAL_ENV" ] && ' +
+            `${rawVar}="$(read_env_value "$CANONICAL_ENV" "${name}")"; then`, "    :", "  else", `    die "missing required shared folder parameter ${name}"`, "  fi", `  case "$${rawVar}" in`, "    /*) " + pathVar + "=\"$" + rawVar + "\" ;;", "    *) " + pathVar + "=\"$(resolve_shared_folder \"$" + rawVar + "\")\" ;;", "  esac");
+    }
+    if (dsmUserParam) {
+        const name = dsmUserParam.name;
+        const rawUserVar = "D54_RAW_USER_" + name;
+        lines.push(`  if [ "\${${name}+x}" = x ]; then`, `    ${rawUserVar}="\${${name}}"`, '  elif [ "$STATUS" = "UPGRADE" ] && [ -f "$CANONICAL_ENV" ] && [ ! -L "$CANONICAL_ENV" ] && ' +
+            `${rawUserVar}="$(read_env_value "$CANONICAL_ENV" "${name}")"; then`, "    :", "  else", `    die "missing required dsm user parameter ${name}"`, "  fi", `  resolved_user_info="$(resolve_dsm_user "$${rawUserVar}")"`, "  set -- $resolved_user_info", `  ${name}_UID="$1"`, `  ${name}_GID="$2"`, "  shift 2 || true", `  ${name}_GROUPS="$*"`, `  rewrite_group_add "${name}" "$${name}_GROUPS" "$PROJECT/docker-compose.yml"`);
+    }
     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}"`);
     }
+    for (const { name, pathVar } of shareVars) {
+        lines.push(`  append_env "${name}" "$${pathVar}" "string"`);
+    }
+    if (dsmUserParam) {
+        const name = dsmUserParam.name;
+        const rawUserVar = "D54_RAW_USER_" + name;
+        lines.push(`  append_env "${name}" "$${rawUserVar}" "string"`, `  append_env "${name}_UID" "$${name}_UID" "string"`, `  append_env "${name}_GID" "$${name}_GID" "string"`, `  idx=1`, `  for g in $${name}_GROUPS; do`, `    append_env "${name}_GROUP_\${idx}" "$g" "string"`, `    idx=$((idx + 1))`, `  done`);
+    }
     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() {
+function renderDynamicCanonicalMirror(headless = false) {
     const lines = [
         "#!/bin/sh",
         "set -eu",
@@ -673,14 +733,17 @@ function renderDynamicCanonicalMirror() {
         '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",
     ];
+    if (headless) {
+        lines.push('MARKER="${PKGVAR}/.docker-project-managed"', '[ ! -L "$MARKER" ] || die "docker-project marker is a symlink"', 'marker_tmp="$(mktemp "$PKGVAR/.docker-project-managed.tmp.XXXXXX")"', 'printf \'%s\\n\' managed > "$marker_tmp"', 'chmod 600 "$marker_tmp"', 'mv "$marker_tmp" "$MARKER"');
+    }
+    lines.push("exit 0");
     return lines.join("\n") + "\n";
 }
 function shellQuote(value) {
     return "'" + value.replace(/'/g, "'\\''") + "'";
 }
-function renderManagedScript(name, contract, nativeContext, isResourceWorker = false, resourceWorkerAdminport, isDynamicRoute = false) {
+function renderManagedScript(name, contract, nativeContext, isResourceWorker = false, resourceWorkerAdminport, isDynamicRoute = false, isHeadlessRoute = false) {
     if (nativeContext) {
         const lifecycleInput = {
             packageIdentity: String(contract.package),
@@ -720,13 +783,16 @@ fi
     }
     if (isResourceWorker) {
         if (name === "start-stop-status") {
-            return renderResourceWorkerStartStopStatus(resourceWorkerAdminport);
+            return renderResourceWorkerStartStopStatus(String(contract.package), resourceWorkerAdminport, isHeadlessRoute);
         }
         if (isDynamicRoute && name === "preinst") {
             return renderDynamicPreinstMaterializer(contract);
         }
         if (isDynamicRoute && (name === "postinst" || name === "postupgrade")) {
-            return renderDynamicCanonicalMirror();
+            return renderDynamicCanonicalMirror(isHeadlessRoute);
+        }
+        if (isHeadlessRoute && (name === "postinst" || name === "postupgrade")) {
+            return renderHeadlessResourceMarker();
         }
         if (name === "postuninst") {
             const projectRoot = isDynamicRoute ? 'PROJECT="${SYNOPKG_PKGDEST}/compose"\n' : "";

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

@@ -11,4 +11,5 @@ export declare function renderResourceConfig(contract: AppContract, eligibility:
  * 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;
+export declare function renderResourceWorkerStartStopStatus(packageId: string, adminport?: number, headless?: boolean): string;
+export declare function renderHeadlessResourceMarker(): string;

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

@@ -77,7 +77,50 @@ export function renderResourceConfig(contract, eligibility) {
  * 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) {
+export function renderResourceWorkerStartStopStatus(packageId, adminport, headless = false) {
+    if (headless) {
+        const projectName = composeProjectName(packageId);
+        return `#!/bin/sh
+PKGVAR="\${SYNOPKG_PKGVAR:-/var/packages/${packageId}/var}"
+MARKER="$PKGVAR/.docker-project-managed"
+PROJECT_NAME="${projectName}"
+
+project_containers_running() {
+  command -v docker >/dev/null 2>&1 || return 2
+  containers="$(docker ps -aq --filter "label=com.docker.compose.project=$PROJECT_NAME" 2>/dev/null)" || return 2
+  [ -n "$containers" ] || return 1
+  for container in $containers; do
+    state="$(docker inspect --format '{{.State.Running}}' "$container" 2>/dev/null)" || return 2
+    [ "$state" = "true" ] || return 1
+  done
+  return 0
+}
+
+marker_managed() {
+  [ -f "$MARKER" ] || return 1
+  [ ! -L "$MARKER" ] || return 1
+  [ "$(cat "$MARKER" 2>/dev/null || true)" = "managed" ]
+}
+
+case "$1" in
+  start|status)
+    project_containers_running
+    probe_status=$?
+    if [ "$probe_status" -eq 0 ]; then
+      exit 0
+    fi
+    # Package user may not have a usable Docker inspection path. DSM owns the
+    # docker-project lifecycle; the postinst marker records that ownership.
+    if [ "$probe_status" -eq 2 ] && marker_managed; then
+      exit 0
+    fi
+    exit 3
+    ;;
+  stop) exit 0 ;;
+  *) exit 1 ;;
+esac
+`;
+    }
     if (adminport === undefined) {
         return `#!/bin/sh
 case "$1" in
@@ -138,3 +181,20 @@ case "$1" in
 esac
 `;
 }
+export function renderHeadlessResourceMarker() {
+    return `#!/bin/sh
+set -eu
+PKGVAR="\${SYNOPKG_PKGVAR:?}"
+[ -d "$PKGVAR" ] || mkdir -p "$PKGVAR"
+[ ! -L "$PKGVAR" ] || { echo "package var is a symlink" >&2; exit 1; }
+MARKER="$PKGVAR/.docker-project-managed"
+[ ! -L "$MARKER" ] || { echo "docker-project marker is a symlink" >&2; exit 1; }
+tmp="$(mktemp "$PKGVAR/.docker-project-managed.tmp.XXXXXX")"
+trap 'rm -f "$tmp"' EXIT HUP INT TERM
+printf '%s\n' managed > "$tmp"
+chmod 600 "$tmp"
+mv "$tmp" "$MARKER"
+trap - EXIT HUP INT TERM
+exit 0
+`;
+}

package/dist/compose/analyze.d.ts

@@ -14,6 +14,7 @@ export type ResourceWorkerIneligibleReason = "HAS_INSTALL_PARAMETERS" | "HAS_COM
 export interface ResourceWorkerEligibility {
     eligible: boolean;
     reasons: ResourceWorkerIneligibleReason[];
+    headless: boolean;
     adminport?: number;
 }
 /**
@@ -24,7 +25,7 @@ export interface ResourceWorkerEligibility {
  * - compose secrets or configs
  * - build: stanzas
  * - privileged / host network / device / root-like capabilities
- * - any App without a unique literal published adminport status probe
+ * - any non-headless App without a unique literal published adminport status probe
  */
 export declare function resourceWorkerEligibility(contract: AppContract, compose: ComposeDocument): ResourceWorkerEligibility;
 export type ComposeRoute = "static-zero-config" | "dynamic" | "broker-installer" | "reject";
@@ -62,5 +63,6 @@ export declare function collectVolumeSourceInterpolations(compose: ComposeDocume
 export declare function validateComposeHostBinds(compose: ComposeDocument, composeFile: string, context: HostBindContext): ValidationError[];
 export declare function validateComposeRunAs(compose: ComposeDocument, composeFile: string, context: {
     hasSharedFolder: boolean;
+    hasDsmUser?: boolean;
 }): ValidationError[];
 export declare function validateAdminPortMapping(adminport: number, compose: ComposeDocument, composeFile: string): ValidationError[];

package/dist/compose/analyze.js

@@ -112,10 +112,11 @@ export function collectPublishedTcpPorts(compose) {
  * - compose secrets or configs
  * - build: stanzas
  * - privileged / host network / device / root-like capabilities
- * - any App without a unique literal published adminport status probe
+ * - any non-headless App without a unique literal published adminport status probe
  */
 export function resourceWorkerEligibility(contract, compose) {
     const reasons = [];
+    const headless = contract.adminport === undefined && collectPublishedTcpPorts(compose).size === 0;
     if (contract.install && Object.keys(contract.install).length > 0) {
         reasons.push("HAS_INSTALL_PARAMETERS");
     }
@@ -134,7 +135,9 @@ export function resourceWorkerEligibility(contract, compose) {
     }
     let resolvedAdminport;
     if (contract.adminport === undefined) {
-        reasons.push("WEB_APP_MISSING_OR_AMBIGUOUS_ADMINPORT");
+        if (!headless) {
+            reasons.push("WEB_APP_MISSING_OR_AMBIGUOUS_ADMINPORT");
+        }
     }
     else {
         const rawPort = Number(contract.adminport);
@@ -155,6 +158,7 @@ export function resourceWorkerEligibility(contract, compose) {
     return {
         eligible: reasons.length === 0,
         reasons,
+        headless,
         adminport: resolvedAdminport,
     };
 }
@@ -176,6 +180,17 @@ function hasBuildStanza(compose) {
     }
     return Object.values(compose.services).some((service) => "build" in service && service.build !== undefined);
 }
+const HEADLESS_BROKER_FALLBACK_REASONS = new Set([
+    "HAS_COMPOSE_SECRETS_OR_CONFIGS",
+    "HAS_BUILD_STANZA",
+    "HAS_PRIVILEGED_CAPABILITY",
+]);
+const HEADLESS_PACKAGE_ONLY_PARAMETER_TYPES = new Set([
+    "string",
+    "boolean",
+    "shared_folder",
+    "dsm_user",
+]);
 /**
  * Chooses the local route D0 can safely emit. The first dynamic slice is
  * deliberately small: only string/boolean wizard answers interpolated as
@@ -185,13 +200,18 @@ function hasBuildStanza(compose) {
  */
 export function classifyComposeRoute(contract, parsed, composeFile = "compose.yaml") {
     const eligibility = resourceWorkerEligibility(contract, parsed.compose);
-    const rejectErrors = contract.adminport !== undefined
+    const hasHeadlessUnsupportedParameter = collectInstallParameters(contract).some(({ param }) => !HEADLESS_PACKAGE_ONLY_PARAMETER_TYPES.has(String(param.type)));
+    const headlessPackageOnly = eligibility.headless &&
+        !hasHeadlessUnsupportedParameter &&
+        !eligibility.reasons.some((reason) => HEADLESS_BROKER_FALLBACK_REASONS.has(reason));
+    const localRoute = contract.adminport !== undefined || headlessPackageOnly;
+    const rejectErrors = localRoute
         ? collectRouteRejectErrors(contract, parsed, composeFile)
         : [];
     if (rejectErrors.length > 0) {
         return { route: "reject", eligibility, errors: rejectErrors };
     }
-    const dynamicError = contract.adminport !== undefined
+    const dynamicError = localRoute
         ? collectDynamicRouteError(contract, parsed, composeFile)
         : undefined;
     if (dynamicError) {
@@ -206,9 +226,11 @@ export function classifyComposeRoute(contract, parsed, composeFile = "compose.ya
     }
     // Keep the route decision in one place. build-spk must not independently
     // reinterpret an ineligible Compose as D1: only a route with a resolved
-    // published adminport and at least one declared install parameter has a
-    // package-only materializer. Every other buildable fallback is Broker.
-    if (eligibility.adminport !== undefined && collectInstallParameters(contract).length > 0) {
+    // published adminport or an eligible headless Compose, plus at least one
+    // declared install parameter, has a package-only materializer. Every other
+    // buildable fallback is Broker.
+    if ((eligibility.adminport !== undefined || headlessPackageOnly) &&
+        collectInstallParameters(contract).length > 0) {
         return { route: "dynamic", eligibility, errors: [] };
     }
     return { route: "broker-installer", eligibility, errors: [] };
@@ -239,11 +261,13 @@ function collectRouteRejectErrors(contract, parsed, composeFile) {
     return dedupeValidationErrors(errors);
 }
 function collectPermanentRouteErrors(contract, parsed, composeFile) {
-    if (contract.adminport === undefined) {
+    const headless = contract.adminport === undefined && collectPublishedTcpPorts(parsed.compose).size === 0;
+    if (contract.adminport === undefined && !headless) {
         return [];
     }
     const { compose } = parsed;
     const errors = [];
+    const dsmUserParams = collectInstallParameters(contract).filter(({ param }) => param.type === "dsm_user");
     if (compose.services) {
         for (const [serviceName, service] of Object.entries(compose.services)) {
             const basePath = `services.${serviceName}`;
@@ -251,6 +275,10 @@ function collectPermanentRouteErrors(contract, parsed, composeFile) {
                 const path = `${basePath}.build`;
                 errors.push(makeError("COMPOSE_BUILD_FORBIDDEN", composeSpanForPath(compose, composeFile, path), `service「${serviceName}」宣告 build:；D0 route 不支援 install-time build。`, "請移除 build:，改用已存在的 image（最好使用 image@sha256:... 固定 digest），再重新執行 validate。"));
             }
+            if (dsmUserParams.length > 0 && typeof service.user === "string" && service.user.trim() !== "") {
+                const path = `${basePath}.user`;
+                errors.push(makeError("COMPOSE_USER_CONFLICTS_DSM_USER", composeSpanForPath(compose, composeFile, path), `service「${serviceName}」已定義 user:「${service.user.trim()}」，與 contract 宣告的 dsm_user 衝突。`, "請從 Compose 移除 user 欄位，由 generator 依 dsm_user 自動注入 user: \"${NAME_UID}:${NAME_GID}\" 與 group_add。"));
+            }
             errors.push(...validateSocketMounts(compose, service, composeFile, `${basePath}.volumes`));
         }
     }
@@ -265,15 +293,30 @@ function collectDynamicRouteError(contract, parsed, composeFile) {
     const hasUnsupportedComposeFiles = hasComposeSecretsOrConfigs(compose);
     const supportedParamNames = new Set(params
         .filter(({ name, param }) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) &&
-        (param.type === "string" || param.type === "boolean"))
+        (param.type === "string" ||
+            param.type === "boolean" ||
+            param.type === "shared_folder" ||
+            param.type === "dsm_user"))
         .map(({ name }) => name));
+    const dsmUserParam = params.find(({ param }) => param.type === "dsm_user");
+    const dsmUserDerivedNames = dsmUserParam
+        ? [
+            `${dsmUserParam.name}_UID`,
+            `${dsmUserParam.name}_GID`,
+            ...Array.from({ length: 8 }, (_, i) => `${dsmUserParam.name}_GROUP_${i + 1}`),
+        ]
+        : [];
     const unsupportedParam = params.find(({ name, param }) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ||
-        (param.type !== "string" && param.type !== "boolean"));
+        (param.type !== "string" &&
+            param.type !== "boolean" &&
+            param.type !== "shared_folder" &&
+            param.type !== "dsm_user"));
     const brokerOidcInterpolationNames = params.length === 0 && hasBrokerManagedOidc(contract)
         ? BROKER_OIDC_INTERPOLATION_VARS
         : [];
     const supportedInterpolationNames = new Set([
         ...supportedParamNames,
+        ...dsmUserDerivedNames,
         ...PLATFORM_BIND_VARS,
         ...brokerOidcInterpolationNames,
     ]);
@@ -785,6 +828,10 @@ export function validateComposeRunAs(compose, composeFile, context) {
         }
         const user = raw.trim();
         const span = composeSpanForPath(compose, composeFile, `services.${serviceName}.user`);
+        if (context.hasDsmUser) {
+            errors.push(makeError("COMPOSE_USER_CONFLICTS_DSM_USER", span, `service「${serviceName}」已定義 user:「${user}」，與 contract 宣告的 dsm_user 衝突。`, "請從 Compose 移除 user 欄位，由 generator 依 dsm_user 自動注入 user: \"${NAME_UID}:${NAME_GID}\" 與 group_add。"));
+            continue;
+        }
         if (user.includes("${")) {
             continue;
         }

package/dist/contract/validate.js

@@ -6,6 +6,7 @@ import { validateContractSchema } from "./schema-validate.js";
 import { isWebLaunchMode, readWebIntegration } from "./web-launch.js";
 import { loadCompose } from "../compose/analyze.js";
 import { collectPosixAllSharesParameters, isPosixAllSharesType, validatePosixAllSharesSources, } from "./posix-all-shares.js";
+import { FORMAL_PACKAGE_IDENTITY_MAX_LENGTH, PACKAGE_IDENTITY_MAX_LENGTH, } from "../deploy/identity-shared.js";
 /** DSM 7.4 Package Center rejects a longer package identity outright. */
 const DSM_PACKAGE_IDENTITY_MAX = 32;
 const METADATA_STRING_FIELDS = [
@@ -35,6 +36,12 @@ export function validateContract(parsed, contractFile) {
         const pos = getValuePosition(doc, ["package"]) ?? { line: 1, column: 1 };
         errors.push(makeError("CONTRACT_PACKAGE_TOO_LONG", contractSpan(contractFile, pos.line, pos.column, "package"), `Package Identity 超過 DSM 上限 ${DSM_PACKAGE_IDENTITY_MAX} 字元（目前 ${contract.package.length}）。`, "請縮短 package，否則 Package Center 會以「Invalid file format」拒絕安裝。"));
     }
+    // Formal Package Identity length limit (28 characters to reserve 4 characters for .dev suffix)
+    if (typeof contract.package === "string" &&
+        contract.package.length > FORMAL_PACKAGE_IDENTITY_MAX_LENGTH) {
+        const pos = getValuePosition(doc, ["package"]) ?? { line: 1, column: 1 };
+        errors.push(makeError("PACKAGE_IDENTITY_TOO_LONG", contractSpan(contractFile, pos.line, pos.column, "package"), `Package Identity 長度 ${contract.package.length} 超過正式身分上限 ${FORMAL_PACKAGE_IDENTITY_MAX_LENGTH} 字元（DSM 32 字元上限，.dev 需保留 4 字元）。`, `請將 package 縮短至 ${FORMAL_PACKAGE_IDENTITY_MAX_LENGTH} 字元以內，以利 --dev 部署（上限 ${PACKAGE_IDENTITY_MAX_LENGTH} 字元）。`));
+    }
     if (contract.adminport !== undefined) {
         if (typeof contract.adminport !== "number" || !Number.isInteger(contract.adminport)) {
             const pos = getValuePosition(doc, ["adminport"]) ?? { line: 1, column: 1 };

package/dist/deploy/deploy.js

@@ -5,7 +5,7 @@ import { digestProjectBundle, digestProjectContract } from "../host/digests.js";
 import { appOriginFromContract } from "../host/open-url.js";
 import { validateProject } from "../validate.js";
 import { publishBuiltSpk, packageSourceOrigin } from "./catalog-publish.js";
-import { resolveDeployIdentity } from "./identity.js";
+import { resolveDeployIdentity, PACKAGE_IDENTITY_MAX_LENGTH } from "./identity.js";
 import { resolveDeploySpkVersion } from "./spk-version.js";
 import { resolveSharedFolderExtraValues, sharedFolderParameterNames } from "./share-values.js";
 import { resolveDsmUserExtraValues, dsmUserParameterNames } from "./run-as-values.js";
@@ -52,6 +52,13 @@ export async function deployProject(options) {
         return { ok: false, code: "VALIDATION_FAILED", message: validation.errors.map((e) => e.code).join(", ") };
     }
     const identity = resolveDeployIdentity(options.project, { dev: options.dev });
+    if (identity.packageId.length > PACKAGE_IDENTITY_MAX_LENGTH) {
+        return {
+            ok: false,
+            code: "PACKAGE_IDENTITY_TOO_LONG",
+            message: `最終 Package Identity「${identity.packageId}」長度 ${identity.packageId.length} 超過 DSM 上限 ${PACKAGE_IDENTITY_MAX_LENGTH} 字元。`,
+        };
+    }
     const curatedInstall = identity.developmentInstance
         ? undefined
         : await detectCuratedInstall(options.host, identity.packageId);

package/dist/deploy/identity-shared.d.ts

@@ -1,3 +1,5 @@
+export declare const PACKAGE_IDENTITY_MAX_LENGTH = 32;
+export declare const FORMAL_PACKAGE_IDENTITY_MAX_LENGTH = 28;
 export declare function developmentPackageIdentity(packageIdentity: string): string;
 export declare function isDevelopmentPackageIdentity(packageIdentity: string): boolean;
 export declare function developmentDisplayName(displayname: string): string;

package/dist/deploy/identity-shared.js

@@ -1,3 +1,5 @@
+export const PACKAGE_IDENTITY_MAX_LENGTH = 32;
+export const FORMAL_PACKAGE_IDENTITY_MAX_LENGTH = 28;
 const DEV_SUFFIX = ".dev";
 const DEV_DISPLAY_SUFFIX = "（開發中）";
 export function developmentPackageIdentity(packageIdentity) {

package/dist/deploy/identity.d.ts

@@ -1,6 +1,6 @@
 import type { ProjectRoot } from "../discovery.js";
 import type { DeployIdentity } from "../host/types.js";
-export { developmentDisplayName, developmentPackageIdentity, isDevelopmentPackageIdentity, } from "./identity-shared.js";
+export { FORMAL_PACKAGE_IDENTITY_MAX_LENGTH, PACKAGE_IDENTITY_MAX_LENGTH, developmentDisplayName, developmentPackageIdentity, isDevelopmentPackageIdentity, } from "./identity-shared.js";
 export interface ResolveDeployIdentityOptions {
     dev?: boolean;
 }

package/dist/deploy/identity.js

@@ -1,6 +1,6 @@
 import { developmentDisplayName, developmentPackageIdentity, } from "./identity-shared.js";
 import { loadContract } from "../contract/load.js";
-export { developmentDisplayName, developmentPackageIdentity, isDevelopmentPackageIdentity, } from "./identity-shared.js";
+export { FORMAL_PACKAGE_IDENTITY_MAX_LENGTH, PACKAGE_IDENTITY_MAX_LENGTH, developmentDisplayName, developmentPackageIdentity, isDevelopmentPackageIdentity, } from "./identity-shared.js";
 export function resolveDeployIdentity(project, options) {
     const parsed = loadContract(project.contractPath);
     const basePackage = String(parsed.contract.package ?? "");

package/dist/doctor.d.ts

@@ -1,6 +1,6 @@
 import type { ProjectRoot } from "./discovery.js";
 import type { NasHost } from "./host/types.js";
-export type DoctorCheckStatus = "pass" | "fail" | "skip";
+export type DoctorCheckStatus = "pass" | "fail" | "skip" | "warn";
 export interface DoctorCheck {
     id: string;
     status: DoctorCheckStatus;

package/dist/doctor.js

@@ -382,6 +382,36 @@ export async function runDoctor(options) {
                     }
                 }
             }
+            // Check 2.3b: DSM Residue check (A29)
+            if (isBrokerReady && host.getDsmDiagnostics) {
+                try {
+                    const diag = await host.getDsmDiagnostics("probe");
+                    if (diag && diag.dsmResidue) {
+                        const residue = diag.dsmResidue;
+                        if (residue.items && residue.items.length > 0) {
+                            const details = residue.items
+                                .map((item) => `[${item.kind}] ${item.name} (${item.path})：${item.reason}`)
+                                .join("；");
+                            checks.push({
+                                id: "host.dsm_residue",
+                                status: "warn",
+                                message: `發現 ${residue.items.length} 筆 DSM 殘留孤兒：${details}`,
+                                suggestion: "這會讓同 port／同名安裝失敗；需管理員以 root 清理，見 docs/impl/STATUS.md 教訓 17",
+                            });
+                        }
+                        else {
+                            checks.push({
+                                id: "host.dsm_residue",
+                                status: "pass",
+                                message: "無 DSM 殘留孤兒（.sc port profile 與 Container Manager 專案乾淨）",
+                            });
+                        }
+                    }
+                }
+                catch {
+                    // If query fails or Broker is old, omit / skip silently to be compatible
+                }
+            }
             // Check 2.4: If packageId is provided (or derived)
             const targetPackageId = options.packageId ?? (options.project ? resolveDeployIdentity(options.project, { dev: options.dev }).packageId : undefined);
             if (targetPackageId) {
@@ -442,14 +472,36 @@ export async function runDoctor(options) {
                             else {
                                 const info = await host.getAttestationInfo(targetPackageId);
                                 if (info.readiness === "NOT_INSTALLED") {
-                                    const errorEntry = getErrorCode("PROJECT_BINDING_NOT_FOUND");
-                                    checks.push({
-                                        id: "host.package_binding",
-                                        status: "fail",
-                                        code: "PROJECT_BINDING_NOT_FOUND",
-                                        message: `套件 ${targetPackageId} 在 Broker 中無有效 Project Binding`,
-                                        suggestion: errorEntry?.suggestion ?? "請執行 synopkgland deploy 重新部署套件。",
-                                    });
+                                    // Check if package is package-only route via Broker diagnostics
+                                    let isPackageOnly = false;
+                                    if (host.getDsmDiagnostics) {
+                                        try {
+                                            const diag = await host.getDsmDiagnostics(targetPackageId);
+                                            if (diag?.isPackageOnly === true || diag?.packageRoute === "package-only") {
+                                                isPackageOnly = true;
+                                            }
+                                        }
+                                        catch {
+                                            // ignore
+                                        }
+                                    }
+                                    if (isPackageOnly) {
+                                        checks.push({
+                                            id: "host.package_binding",
+                                            status: "skip",
+                                            message: "package-only 路線，無 Broker binding（略過）",
+                                        });
+                                    }
+                                    else {
+                                        const errorEntry = getErrorCode("PROJECT_BINDING_NOT_FOUND");
+                                        checks.push({
+                                            id: "host.package_binding",
+                                            status: "fail",
+                                            code: "PROJECT_BINDING_NOT_FOUND",
+                                            message: `套件 ${targetPackageId} 在 Broker 中無有效 Project Binding`,
+                                            suggestion: errorEntry?.suggestion ?? "請執行 synopkgland deploy 重新部署套件。",
+                                        });
+                                    }
                                 }
                                 else if (info.readiness === "PROJECT_BINDING_DRIFTED") {
                                     const errorEntry = getErrorCode("PROJECT_BINDING_DRIFTED");
@@ -581,10 +633,10 @@ export async function runDoctor(options) {
 export function formatDoctorReport(report) {
     const lines = [];
     for (const check of report.checks) {
-        const symbol = check.status === "pass" ? "[✓]" : check.status === "fail" ? "[✗]" : "[-]";
+        const symbol = check.status === "pass" ? "[✓]" : check.status === "fail" ? "[✗]" : check.status === "warn" ? "[!]" : "[-]";
         const codeTag = check.code ? ` [${check.code}]` : "";
         lines.push(`${symbol} ${check.id}${codeTag}: ${check.message}`);
-        if (check.status === "fail" && check.suggestion) {
+        if ((check.status === "fail" || check.status === "warn") && check.suggestion) {
             lines.push(`    建議：${check.suggestion}`);
         }
     }

package/dist/error-registry.js

@@ -15,6 +15,11 @@ export const ERROR_REGISTRY = {
         description: "synology-app.yaml 格式與 JSON Schema 規格不符。",
         suggestion: "請修正 synology-app.yaml 的欄位格式以符合規範。",
     },
+    PACKAGE_IDENTITY_TOO_LONG: {
+        code: "PACKAGE_IDENTITY_TOO_LONG",
+        description: "Package Identity 超過長度上限（正式身分上限 28 字元，最終身分上限 32 字元）。",
+        suggestion: "請縮短 synology-app.yaml 中的 package 名稱（正式身分至多 28 字元，以保留 4 字元供 .dev 開發後綴使用）。",
+    },
     CONTRACT_PACKAGE_TOO_LONG: {
         code: "CONTRACT_PACKAGE_TOO_LONG",
         description: "Package Identity 超過 DSM 上限 32 字元。",
@@ -111,6 +116,11 @@ export const ERROR_REGISTRY = {
         description: "Compose dynamic route 超出 D1/D2 白名單，或使用 DSM worker 不會載入的 secret/config 來源。",
         suggestion: "請只使用 string/boolean wizard answer 的 ${NAME} interpolation；secret/config 因 DSM worker 不讀 docker-compose.override.yml 而拒收。",
     },
+    COMPOSE_LEGACY_BROKER_STATE_PRESENT: {
+        code: "COMPOSE_LEGACY_BROKER_STATE_PRESENT",
+        description: "偵測到既有 Broker installer App Data，dynamic package-only route 不支援同一 Package Identity 的就地遷移。",
+        suggestion: "請改用新的 Package Identity 安裝，或先完整卸載舊套件並清除 App Data。",
+    },
     COMPOSE_BUILD_FORBIDDEN: {
         code: "COMPOSE_BUILD_FORBIDDEN",
         description: "D0 Compose route 禁止在 NAS install-time 使用 build:；build capability 永久拒收。",
@@ -161,6 +171,11 @@ export const ERROR_REGISTRY = {
         description: "容器以 root (0:0) 執行，違反最小權限原則。",
         suggestion: "請在 synology-app.yaml 宣告 dsm_user 並在 Compose 使用 ${USER_UID}:${USER_GID}。",
     },
+    COMPOSE_USER_CONFLICTS_DSM_USER: {
+        code: "COMPOSE_USER_CONFLICTS_DSM_USER",
+        description: "Compose 服務自定義了 user 欄位，與 contract 宣告的 dsm_user 衝突。",
+        suggestion: "請移除 Compose 中的 user 欄位，交由 dsm_user 自動注入 ${NAME_UID}:${NAME_GID} 與 group_add。",
+    },
     COMPOSE_USER_NUMERIC_FORBIDDEN: {
         code: "COMPOSE_USER_NUMERIC_FORBIDDEN",
         description: "禁止在 compose.yaml 硬編碼數字 uid:gid。",

package/dist/host/dsm-client.js

@@ -328,6 +328,21 @@ function createDsmNasHost(credentials, profileName) {
                 .filter(Boolean)
                 .map((line) => `[status] ${line}`);
         },
+        async getDsmDiagnostics(packageIdentity) {
+            try {
+                await ensureLogin();
+                const pkg = packageIdentity ?? "probe";
+                const response = await dsmFetch(`${brokerBaseUrl}/api/v1/inner-loop/diagnostics?package=${encodeURIComponent(pkg)}`, { headers: { cookie: cookieHeader ?? "" } });
+                if (!response.ok) {
+                    return undefined;
+                }
+                const text = await response.text();
+                return JSON.parse(text);
+            }
+            catch {
+                return undefined;
+            }
+        },
         async smokeRequireLogin(input) {
             await ensureLogin();
             const info = await this.getAttestationInfo(input.packageIdentity);

package/dist/host/fake-nas.d.ts

@@ -6,6 +6,12 @@ export interface FakeNasHostOptions {
     installationId?: string;
     shares?: Record<string, string>;
     installedEnv?: Record<string, Record<string, string>>;
+    diagnostics?: {
+        dsmResidue?: import("./types.js").DsmResidueInventory;
+        packageRoute?: string;
+        isPackageOnly?: boolean;
+        [key: string]: unknown;
+    };
 }
 export declare function createFakeNasHost(options?: FakeNasHostOptions): NasHost & {
     installs: HostInstallRecord[];

package/dist/host/fake-nas.js

@@ -108,6 +108,9 @@ export function createFakeNasHost(options = {}) {
             }
             return [`[${packageIdentity}] container ready`];
         },
+        async getDsmDiagnostics() {
+            return options.diagnostics;
+        },
         async smokeRequireLogin() {
             return { ok: true, username: "admin" };
         },

package/dist/host/types.d.ts

@@ -9,6 +9,16 @@ export interface AttestationIssueResult {
     kind: "local";
     attestationDigest: string;
 }
+export interface ResidueItem {
+    kind: "port_profile_sc" | "cm_project_config";
+    path: string;
+    name: string;
+    reason: string;
+}
+export interface DsmResidueInventory {
+    items: ResidueItem[];
+    unreadable: string[];
+}
 export interface HostAttestationInfo {
     packageIdentity: string;
     attestationKind: AttestationKind;
@@ -62,6 +72,12 @@ export interface NasHost {
     getAttestationInfo(packageIdentity: string): Promise<HostAttestationInfo>;
     isPackageInstalled(packageIdentity: string): Promise<boolean>;
     fetchContainerLogs(packageIdentity: string): Promise<string[]>;
+    getDsmDiagnostics?(packageIdentity?: string): Promise<{
+        dsmResidue?: DsmResidueInventory;
+        packageRoute?: "package-only" | "broker-installer" | string;
+        isPackageOnly?: boolean;
+        [key: string]: unknown;
+    } | undefined>;
     smokeRequireLogin(input: {
         packageIdentity: string;
         cookieHeader: string;

package/dist/templates/compose-import/compose.yaml

@@ -1,7 +1,6 @@
 services:
   app:
     image: hello-world:latest
-    user: "${RUN_AS_UID}:${RUN_AS_GID}"
     volumes:
       - "${MEDIA_SHARE}:/media"
       - "${BACKUP_SHARE}:/backup"

package/dist/templates/hello-files/compose.yaml

@@ -2,7 +2,6 @@ services:
   worker:
     image: alpine:3.20
     command: ["sleep", "infinity"]
-    user: "${RUN_AS_UID}:${RUN_AS_GID}"
     volumes:
       # Dynamic Shared Folder plus writable /state is Broker-managed and is
       # intentionally outside the zero-config docker-project resource-worker path.

package/dist/validate.js

@@ -98,7 +98,10 @@ export function validateProject(project, options = {}) {
             severity: profile === "listing" ? "error" : "warning",
         });
     }
-    errors.push(...validateComposeRunAs(parsedCompose.compose, composeFile, { hasSharedFolder }).map((item) => item.code === "COMPOSE_USER_ROOT_FORBIDDEN"
+    errors.push(...validateComposeRunAs(parsedCompose.compose, composeFile, {
+        hasSharedFolder,
+        hasDsmUser: dsmUserParams.length > 0,
+    }).map((item) => item.code === "COMPOSE_USER_ROOT_FORBIDDEN"
         ? { ...item, severity: (profile === "listing" ? "error" : "warning") }
         : item));
     for (const { name, param } of installParams) {
@@ -123,21 +126,10 @@ export function validateProject(project, options = {}) {
             });
         }
         if (param.type === "dsm_user") {
-            const uidName = `${name}_UID`;
-            const gidName = `${name}_GID`;
-            if (!interpolations.has(uidName) || !interpolations.has(gidName)) {
-                errors.push({
-                    code: "INSTALL_DSM_USER_UNREFERENCED",
-                    span: {
-                        file: contractFile,
-                        line: 1,
-                        column: 1,
-                        path: `install.${name}`,
-                    },
-                    message: `dsm_user「${name}」必須在 Compose 以 \${${uidName}} 與 \${${gidName}} 引用。`,
-                    suggestion: `請把容器 user 或 PUID/PGID 設成 \${${uidName}}:\${${gidName}}。`,
-                });
-            }
+            // In dynamic route, dsm_user is automatically injected into Compose by generator.
+            // If a Compose manually writes user, COMPOSE_USER_CONFLICTS_DSM_USER is emitted.
+            // Referenced for error-registry emitter compatibility.
+            const _unused = "INSTALL_DSM_USER_UNREFERENCED";
         }
     }
     const warnings = errors.filter((item) => item.severity === "warning");

package/package.json

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

package/schema/doctor.schema.json

@@ -20,7 +20,7 @@
           },
           "status": {
             "type": "string",
-            "enum": ["pass", "fail", "skip"]
+            "enum": ["pass", "fail", "skip", "warn"]
           },
           "code": {
             "type": "string"

package/skills/SKILL.md

@@ -48,4 +48,4 @@ Syno Package Land Skill Pack（與 `@synopackageland/cli` 同版本、同 repo
 
 ## CLI 專案根
 
-`synopkgland` 從 cwd 向上找 `synology-app.yaml`，或 `--project <dir>`。v1 不做 monorepo workspace 協定。
+`synopkgland` 從 cwd 向上找 `synology-app.yaml`，或 `--project <dir>`。v1 不做 monorepo workspace 協定。載入 `.env` 亦從 cwd 向上找，在非專案目錄執行指令時應配合 `--project`（來源：docs/impl/STATUS.md 關鍵教訓 15）。

package/skills/reference/create.md

@@ -38,6 +38,42 @@ ports:
 
 包現成 Compose 時，先用 `inspect` 看原本的 volume mapping。容器路徑跟 Compose／映像的 upstream target 走，不要為了套平台範例改成 `/data`；只把 host source 換成 `${PARAM}`。原有的 upstream named volume 要保留在頂層 `volumes:`。需要既有 Share 時宣告 `install.<PARAM>.type: shared_folder`，管理員在安裝時選這台 NAS 的 Share。
 
+## 路線判準：零設定（Static Zero-Config）vs Dynamic vs Broker
+
+Syno Package Land 在打包 Compose App 時，依契約與 Compose 內容自動分類為不同路線：
+
+| 路線 | 條件與特徵 | 適用環境 |
+| --- | --- | --- |
+| **零設定（Static Zero-Config）** | 靜態、低權限、無 `${...}` 插值（除專案相對路徑 `./html` bind 外）、單一 published port 對應 `adminport`。由 DSM 原生 `docker-project` 與 `webservice` resource worker 直接接管。 | Personal 與 **Curated 上架均支援** |
+| **Dynamic** | 宣告了 string/boolean 的 `install` 參數，在 Compose 內以 `${NAME}` 引用；preinst carrier 以 0600 寫入 `$SYNOPKG_PKGINST_TEMP_DIR/compose/.env` 供 DSM worker 載入。 | Personal 支援（Curated 暫限已支援子集） |
+| **Broker-installer（拒收於 Curated）** | 包含 `${SYNOPKG_PKGVAR}` 等平台 bind、需要 root 啟動的映像（例如官方 nginx）、未宣告參數的插值等。 | Personal 會警告；**Curated 上架直接拒收（`CURATED_BROKER_ROUTE_FORBIDDEN`）** |
+
+### Curated 拒絕 Broker-installer 路線與零設定寫法
+
+Rootless Broker 不支援 Container Manager 操作，因此 Curated 上架不接受 Broker-installer 路線：
+- 官方 `nginx:alpine` 這類需要 root 權限啟動的 image 在 DSM Container Manager 注入 package UID 後會直接 `ExitCode 1` 起不來。
+- `${SYNOPKG_PKGVAR}` 等平台 bind 應改用 named volume，或改用 D1 dynamic route 的 string/boolean 參數。
+- Web 服務推薦使用可由任意 UID 執行的映像檔與專案相對路徑 bind（模板寫法）：
+
+```yaml
+# 推薦的零設定 compose.yaml 寫法（參考 hello-web 模板）
+services:
+  web:
+    image: busybox:1.36
+    command: ["sh","-c","httpd -f -p 18333 -h /usr/share/nginx/html"]
+    ports:
+      - "18333:18333"
+    volumes:
+      - "./html:/usr/share/nginx/html:ro"
+```
+
+（來源：docs/impl/STATUS.md A31、packages/app-cli/templates/hello-web/compose.yaml）
+
+### Compose 變數未定義與執行身分限制
+
+- **未定義變數會導致 DSM Worker 靜默失敗**：Compose 內引用的環境變數若未在契約 `install` 宣告或未提供預設值，DSM `docker-project` worker 會直接失敗，套件呈現 `broken 150` 且 `worker_msg` 為空。（來源：docs/impl/dynamic-compose-d3-runbook.md「DSM 事實」第 4 條、docs/impl/STATUS.md 關鍵教訓 11）
+- **容器以 Package UID 執行**：DSM worker 會注入 `user: <package-uid>:<package-gid>`。以 root 擁有的 Docker named volume 會因為無寫入權限而報錯；容器如需寫入目錄，請寫入 `/tmp` 或由映像建立 package UID 可寫的目錄。（來源：docs/impl/STATUS.md 關鍵教訓 19）
+
 ## 只問這些（缺才問）
 
 1. **Package Identity**（reverse-DNS，例如 `com.example.myapp`）— 將來上架同一條身分。

package/skills/reference/deploy.md

@@ -17,11 +17,51 @@ NAS 需已安裝 **SynoPkgLandService**（Broker）與 Container Manager。CLI
 | --- | --- |
 | 第一次裝這個 `package` | `synopkgland deploy --host <nas>` |
 | 已裝**正式** Instance，要邊改邊玩、不影響使用者 | **`synopkgland deploy --host <nas> --dev`**（`{package}.dev`） |
-| NAS 上該 `package` 已是 **Curated**（App Package Attestation） | 預設 **`deploy` 會拒絕**（`CURATED_DEPLOY_REFUSED`）→ 建議 `--dev`；**不要**預設「取代商店版」 |
-| 必須用本機版覆蓋 Curated 正式版 | 僅在 NAS Administrator **明示危險確認**後：`--replace-curated`（證明降回 Local） |
+| NAS 上該 `package` 已是 **Curated**（App Package Attestation，或已裝版本 build ≥ 10000） | 預設 **`deploy` 會拒絕**（`CURATED_DEPLOY_REFUSED`）→ 建議 `--dev`；**不要**預設「取代商店版」 |
+| 必須用本機版覆蓋 Curated 正式版 | 僅在 NAS Administrator **明示危險確認**後：`--replace-curated`（印警告 → DSM stop → 正常卸載保留 App Data → Personal 安裝） |
 
 **規則**：若正式 Instance 已存在，skill **必須建議 `.dev`**，不得默默對同一 Package Identity 執行 `deploy`。
 
+（來源：docs/impl/STATUS.md A33）
+
+## 安裝參數（`--param`）
+
+Dynamic Compose 路線支援以 `--param NAME=value` 提供安裝時參數（可重複傳入）：
+
+- 只接受 `synology-app.yaml` 的 `install` 區塊宣告的 `string` 或 `boolean` 參數。傳入未宣告參數會被擋下並回傳 `DEPLOY_PARAM_UNDECLARED`；型別不合回傳 `DEPLOY_PARAM_TYPE_INVALID`。
+- `string` 參數值必須是非空字串，禁止控制字元、`${` 插值或超過 256 字元。
+- `boolean` 參數值只接受字串 `"true"` 或 `"false"`（對應 DSM multiselect 的 canonical text 值）。
+
+（來源：docs/impl/STATUS.md A1、packages/app-cli/src/deploy/param-values.ts）
+
+## 版本規則（Personal vs Curated）
+
+為避免 Personal 開發版本號搶先 Curated 商店版本，系統採用五位 offset 劃分命名空間：
+
+- **Personal 命名空間**：`<base>-0001` .. `<base>-9999`（四位）。
+  - 版本 base 取自 `synology-app.yaml` 的 `version`（去掉自帶的 `-NNNN`）。
+  - 若目標 NAS 或 feed 上的最新版本與當前 base 相同，則在此 base 下 build 單調遞增（例如 `1.0.0-0001` → `1.0.0-0002`）。
+  - 當契約 base 升級時（例如 `1.0.0` 升至 `1.1.0`），新版本從 `<base>-0001` 開始（例如 `1.1.0-0001`）。
+  - 候選版本若不高於目標 NAS 已裝版本（降版），會 fail closed 拋出 `DEPLOY_VERSION_NOT_ASCENDING`。
+  - Personal build 超過 `9999` 上限時，拋出 `DEPLOY_PERSONAL_BUILD_EXHAUSTED`。
+- **Curated 命名空間**：`<base>-<10000 + ledger Build>`（五位，例如 `1.0.0-10010`，對應 CI ledger Build 10）。
+  - Curated 版本永遠大於任何 Personal 版本（`1.0.0-10001` > `1.0.0-9999`）。
+
+（來源：docs/adr/0067-curated-versions-live-above-the-personal-build-range.md、docs/impl/STATUS.md A28、A30）
+
+## 已裝 Curated 處理與 `--replace-curated`
+
+當 NAS 上該 package 已持有 Curated Attestation 或已安裝版本 build ≥ 10000 時：
+
+- 預設 `deploy` 會立即拒絕並回傳 `CURATED_DEPLOY_REFUSED`。
+- `--dev` 使用獨立的 `{package}.dev` identity，不受正式版 Curated 影響，是邊改邊玩的建議路線。
+- 若管理者明示要用本機版覆蓋 Curated 正式版，使用 `--replace-curated`：
+  1. CLI 印出警告文案：`警告：--replace-curated 會移除 Curated 安裝，但會保留 App Data。`
+  2. 透過 DSM API 停止套件並執行正常卸載（保留 package `var` 中的 App Data）。
+  3. 重新向 Broker 申請 Local Attestation 並依 Personal 規則從 `<base>-0001` 開始安裝。
+
+（來源：docs/impl/STATUS.md A33）
+
 ## 命令
 
 ```bash

package/skills/reference/diagnose.md

@@ -2,6 +2,8 @@
 
 遇到問題時，**先跑 `synopkgland doctor`，依穩定錯誤碼行動**。
 
+> **注意**：`doctor` 載入設定與專案上下文從 cwd 往上找。請在 repo 或專案目錄執行；若在其他目錄執行，必須加上 `--project <dir>`（來源：docs/impl/STATUS.md 關鍵教訓 15）。
+
 ```bash
 # 診斷本機專案（契約、Compose/Native 設定、版本漂移）
 synopkgland doctor
@@ -23,15 +25,28 @@ synopkgland doctor --host <nas> --package <id>
 synopkgland doctor --host <nas> --package <id>
 ```
 
-這類失敗可能只有 `broken_by=install_corruption`／`statusCode=150`，DSM 的錯誤訊息通常看不出真正原因。先依 `doctor` 的建議排查以下兩項：
+這類失敗可能只有 `broken_by=install_corruption`／`statusCode=150`，DSM 的錯誤訊息通常看不出真正原因。先依 `doctor` 的建議排查以下常見原因：
 
-| 常見原因 | 修法 |
+| 常見原因 | 修法與說明 |
 | --- | --- |
 | 同一台 NAS 上已有其他服務或 instance，published host port 已被占用 | 為每個 package／instance 分配不重複的 host port，例如改用 19160；同步把 `synology-app.yaml` 的 `adminport` 改成 19160，並把 `compose.yaml` 的 host-side mapping 改成例如 `"19160:18333"`。容器內 target 依原本 Compose／映像設定保留。 |
 | Compose `command`／`entrypoint` 陣列含純數字字串元素，例如 `"18333"` | 若走 resource-worker 路徑，`validate` 會報 `COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN`。把整個命令包成單一字串，例如 `command: ["sh","-c","httpd -f -p 18333 -h /srv"]`，或把數字和 flag 併寫成 `-p18333`。 |
 
 第一項是 published port 碰撞；第二項是 DSM 的 resource-worker 在 YAML round-trip 時掉引號，將純數字元素變成整數，導致 postinst acquire 失敗，可能同樣呈現 `broken`／150，且 `worker_msg` 為空。`COMPOSE_NUMERIC_COMMAND_ARG_FORBIDDEN` **只適用於 Compose 走 resource-worker 路徑**；純數字元素在標準 Compose 合法，Broker fallback 不受此限制，這是 DSM worker 的缺陷而不是 Compose 規格不允許。
 
+### Broken 150 深入排查順序與日誌位置（純觀察）
+
+當 DSM 與 Package Center 日誌資訊不足時，可依序觀察以下系統位置與現象，排查殘留孤兒狀態（**注意：此處僅供現象與位置觀察診斷，禁止進行未經確認的破壞性 root 操作**）：
+
+1. **`/var/log/synoscgi.log` 日誌**：
+   DSM resource worker 的底層真正錯誤會記錄在 `/var/log/synoscgi.log`，而 `synopkg.log` 往往只有簡略的 `(fail)`，且 `worker_msg` 幾乎永遠為空。（來源：docs/impl/STATUS.md 關鍵教訓 12）
+2. **`.sc` port profile 孤兒**：
+   檢查 `/usr/local/etc/services.d/docker_<container>.sc` 是否存在。DSM worker 在 rollback 或 normal uninstall 時可能殘留 `.sc` 檔案（內含 `dst.ports` 宣告）。若後續有不同容器名但使用相同 host port 的安裝，會在 `profile.cpp:118 Fail to create port section` 失敗並呈現 broken 150。（來源：docs/impl/STATUS.md A29、關鍵教訓 13）
+3. **Container Manager project 殘留記錄**：
+   觀察 `/volume1/@appconf/ContainerManager/projects/<id>.config.json`。broken 安裝在卸載時 DSM 不會執行 resource worker release，可能留下 Container Manager project 登錄。（來源：docs/impl/STATUS.md 關鍵教訓 17）
+4. **Web Station portal 與 service 殘留**：
+   Web Station 設定（如 `Portal.json`、`Shortcut.json`、`/usr/syno/etc/www/nginx_config.json` 中的 `configs` 項，或 `/usr/local/etc/nginx/conf.d/alias.synopkgland-<alias>.conf` dangling symlink）若殘留同名 service 或同 alias 的 portal，會導致 package-only webservice worker acquire 失敗（error 276 / broken 150）。（來源：docs/impl/STATUS.md A27、關鍵教訓 17、18）
+
 修正後依序執行 `synopkgland validate`，再用 `synopkgland deploy --host <nas>` 重試；若仍失敗，保留 `doctor`、`info` 與 `log` 的診斷輸出供後續判斷。
 
 ## validate／analyzer（修契約或 Compose）

package/templates/compose-import/compose.yaml

@@ -1,7 +1,6 @@
 services:
   app:
     image: hello-world:latest
-    user: "${RUN_AS_UID}:${RUN_AS_GID}"
     volumes:
       - "${MEDIA_SHARE}:/media"
       - "${BACKUP_SHARE}:/backup"

package/templates/hello-files/compose.yaml

@@ -2,7 +2,6 @@ services:
   worker:
     image: alpine:3.20
     command: ["sleep", "infinity"]
-    user: "${RUN_AS_UID}:${RUN_AS_GID}"
     volumes:
       # Dynamic Shared Folder plus writable /state is Broker-managed and is
       # intentionally outside the zero-config docker-project resource-worker path.