@synopackageland/cli 0.3.4 → 0.3.6

package/dist/build-spk/generator.js

@@ -17,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";
@@ -161,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 });
@@ -192,6 +192,11 @@ export async function buildSpk(options) {
                 copyFileSync(options.project.composePath, join(resourceProjectDir, "docker-compose.yml"));
             }
             chmodSync(join(resourceProjectDir, "docker-compose.yml"), FILE_MODE);
+            const routeMarkerDir = join(staging, "package", ".synopkgland");
+            mkdirSync(routeMarkerDir, { recursive: true });
+            const routeMarker = join(routeMarkerDir, "route");
+            writeFileSync(routeMarker, "package-only", "utf8");
+            chmodSync(routeMarker, FILE_MODE);
         }
         const htmlDir = join(options.project.root, "html");
         if (existsSync(htmlDir)) {
@@ -580,6 +585,7 @@ function renderUninstallWizard() {
             ],
         }];
 }
+const LEGACY_BROKER_STATE_REGISTRY_CODE = "COMPOSE_LEGACY_BROKER_STATE_PRESENT";
 function renderDynamicPreinstMaterializer(contract) {
     const allParams = collectInstallParameters(contract);
     const scalarParams = allParams.filter(({ param }) => param.type === "string" || param.type === "boolean");
@@ -591,6 +597,18 @@ function renderDynamicPreinstMaterializer(contract) {
         "umask 077",
         "# 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"',
@@ -677,12 +695,13 @@ function renderDynamicPreinstMaterializer(contract) {
     }
     if (dsmUserParam) {
         const name = dsmUserParam.name;
-        lines.push(`  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`);
+        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",
@@ -719,14 +738,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),
@@ -766,13 +788,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";

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,7 +261,8 @@ 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;

package/dist/doctor.js

@@ -6,6 +6,19 @@ import { loadContract } from "./contract/load.js";
 import { getErrorCode } from "./error-registry.js";
 import { dsmFetch } from "./host/dsm-http.js";
 import { appOriginFromContract } from "./host/open-url.js";
+function packageRouteFromDiagnostics(diagnostics) {
+    switch (diagnostics?.packageRoute) {
+        case "package-only":
+        case "broker-installer":
+        case "unknown":
+            return diagnostics.packageRoute;
+        default:
+            break;
+    }
+    // Keep compatibility with the boolean-only response emitted by older
+    // Brokers, but never infer broker-installer from missing evidence.
+    return diagnostics?.isPackageOnly === true ? "package-only" : "unknown";
+}
 const PROJECT_FOUR_FILES = ["synology-app.yaml", "README.md", "icon.png"];
 function packageFailureSummary(state) {
     const fields = [];
@@ -472,14 +485,44 @@ 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 the diagnosed route before treating a missing binding
+                                    // as a Broker-installer failure. Unknown is deliberately
+                                    // non-failing because the Broker may not be able to read the
+                                    // DSM package resource.
+                                    let packageRoute = "unknown";
+                                    if (host.getDsmDiagnostics) {
+                                        try {
+                                            const diag = await host.getDsmDiagnostics(targetPackageId);
+                                            packageRoute = packageRouteFromDiagnostics(diag);
+                                        }
+                                        catch {
+                                            // ignore
+                                        }
+                                    }
+                                    if (packageRoute === "package-only") {
+                                        checks.push({
+                                            id: "host.package_binding",
+                                            status: "skip",
+                                            message: "package-only 路線，無 Broker binding（略過）",
+                                        });
+                                    }
+                                    else if (packageRoute === "unknown") {
+                                        checks.push({
+                                            id: "host.package_binding",
+                                            status: "skip",
+                                            message: "Broker 無法判定套件路線，略過 Package 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");

package/dist/error-registry.js

@@ -116,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 永久拒收。",

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

@@ -1,4 +1,4 @@
-import type { AttestationKind, HostInstallRecord, NasHost } from "./types.js";
+import type { AttestationKind, HostInstallRecord, NasHost, PackageRoute } from "./types.js";
 export interface FakeNasHostOptions {
     curated?: string[];
     dsmOrigin?: string;
@@ -8,6 +8,8 @@ export interface FakeNasHostOptions {
     installedEnv?: Record<string, Record<string, string>>;
     diagnostics?: {
         dsmResidue?: import("./types.js").DsmResidueInventory;
+        packageRoute?: PackageRoute;
+        isPackageOnly?: boolean;
         [key: string]: unknown;
     };
 }

package/dist/host/types.d.ts

@@ -1,5 +1,6 @@
 import type { InstalledPackageState } from "./catalog-install.js";
 export type AttestationKind = "local" | "app-package" | "none";
+export type PackageRoute = "package-only" | "broker-installer" | "unknown";
 export interface DeployIdentity {
     packageId: string;
     displayname: string;
@@ -74,6 +75,8 @@ export interface NasHost {
     fetchContainerLogs(packageIdentity: string): Promise<string[]>;
     getDsmDiagnostics?(packageIdentity?: string): Promise<{
         dsmResidue?: DsmResidueInventory;
+        packageRoute?: PackageRoute;
+        isPackageOnly?: boolean;
         [key: string]: unknown;
     } | undefined>;
     smokeRequireLogin(input: {

package/package.json

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