@synopackageland/cli 0.3.9 → 0.4.0

package/dist/contract/unsupported-types.js

@@ -0,0 +1,49 @@
+import { collectInstallParameters } from "./load.js";
+/**
+ * Install parameter types that the schema still accepts but that have no working
+ * install path on the live package-only route.
+ *
+ * Measured on vt-nas 2026-08-27: both end in DSM broken/150 with no Container
+ * Manager project, while a no-parameter control package installed fine on the
+ * same NAS. `secret` renders its password field and fails; `homes` renders no
+ * input at all. `validate` reports these as warnings so build-spk keeps working
+ * for fixtures that declare them incidentally -- the refusal belongs at the two
+ * gates that actually put an App somewhere: deploy and publish.
+ */
+const UNSUPPORTED_INSTALL_TYPES = new Map([
+    ["secret", "CONTRACT_SECRET_UNSUPPORTED"],
+    ["homes", "CONTRACT_HOMES_UNSUPPORTED"],
+]);
+/** Stable gate code for an install type that only the CLI can materialize. */
+export const POSIX_ALL_SHARES_LISTING_UNSUPPORTED_CODE = "CONTRACT_POSIX_ALL_SHARES_LISTING_UNSUPPORTED";
+/**
+ * Install parameter types that work through `synopkgland deploy` but cannot
+ * honor their declared Share scope through Package Center or a curated
+ * listing. Keep this separate from UNSUPPORTED_INSTALL_TYPES: deploy must
+ * continue to resolve these values from the NAS administrator session.
+ */
+const LISTING_UNSUPPORTED_INSTALL_TYPES = new Map([
+    ["posix_all_shares", POSIX_ALL_SHARES_LISTING_UNSUPPORTED_CODE],
+]);
+export function findUnsupportedInstallTypes(contract) {
+    const found = [];
+    for (const { name, param } of collectInstallParameters(contract)) {
+        const type = typeof param.type === "string" ? param.type : "";
+        const code = UNSUPPORTED_INSTALL_TYPES.get(type);
+        if (code) {
+            found.push({ name, type, code });
+        }
+    }
+    return found;
+}
+export function findListingUnsupportedInstallTypes(contract) {
+    const found = [];
+    for (const { name, param } of collectInstallParameters(contract)) {
+        const type = typeof param.type === "string" ? param.type : "";
+        const code = LISTING_UNSUPPORTED_INSTALL_TYPES.get(type);
+        if (code) {
+            found.push({ name, type, code });
+        }
+    }
+    return found;
+}

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 { getErrorCode } from "../error-registry.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;
@@ -113,6 +114,28 @@ function validateInstallParameters(parsed, contractFile) {
                 errors.push(makeError("INSTALL_STRING_INVALID", contractSpan(contractFile, pos.line, pos.column, `${basePath}.default`), `Install Parameter「${name}」的字串值不合法。`, "請移除控制字元與 ${ 插值語法。"));
             }
         }
+        // A45/A46: both types are in the schema enum but neither has a working
+        // install path on the live package-only route -- measured on vt-nas as DSM
+        // broken/150 with no Container Manager project, against a no-parameter
+        // control that installed fine. Refusing here is what makes the failure
+        // honest: `homes` used to validate, build a valid SPK, and only break at
+        // install time, telling the author nothing.
+        if (type === "secret" || type === "homes") {
+            const pos = getValuePosition(doc, ["install", name, "type"]) ??
+                getValuePosition(doc, ["install", name]) ??
+                { line: 1, column: 1 };
+            const code = type === "secret" ? "CONTRACT_SECRET_UNSUPPORTED" : "CONTRACT_HOMES_UNSUPPORTED";
+            const entry = getErrorCode(code);
+            // A warning here, a hard refusal in deploy/publish. Making validate itself
+            // fail would also fail build-spk, and several existing fixtures declare
+            // these types only incidentally while testing wizard copy, permissions and
+            // script generation -- turning those red would cost real coverage for no
+            // extra safety. Nothing unshippable can reach a NAS or the community repo,
+            // because both gates refuse; the author still learns at validate time.
+            errors.push(makeError(code, contractSpan(contractFile, pos.line, pos.column, `${basePath}.type`), `Install Parameter「${name}」的 type: ${type} 目前沒有可用的安裝路徑，經 Package Center 安裝會以 DSM broken／150 結束；deploy 與 publish 會拒絕。`, entry?.suggestion ?? "請改用其他 install parameter type。", "warning"));
+            // Deliberately no `continue`: the type-specific checks below still apply.
+            // Skipping them once silently dropped CONTRACT_HOMES_PATH_FORBIDDEN.
+        }
         if (type === "homes") {
             const configuredPath = Object.entries(param).find(([key, value]) => key !== "type" &&
                 (key === "default" || (typeof value === "string" && isPhysicalHostPath(value))));
@@ -123,7 +146,7 @@ function validateInstallParameters(parsed, contractFile) {
             const pos = getValuePosition(doc, ["install", name, field]) ??
                 getValuePosition(doc, ["install", name]) ??
                 { line: 1, column: 1 };
-            errors.push(makeError("CONTRACT_HOMES_PATH_FORBIDDEN", contractSpan(contractFile, pos.line, pos.column, `${basePath}.${field}`), `homes Install Parameter「${name}」不得在契約欄位「${field}」指定 NAS 實體路徑或預設值。`, `請保留 install.${name}.type: homes，Compose 只引用 \${${name}}；由 glue／Broker 在安裝時依這台 NAS 的 User Home 設定解析路徑。`));
+            errors.push(makeError("CONTRACT_HOMES_PATH_FORBIDDEN", contractSpan(contractFile, pos.line, pos.column, `${basePath}.${field}`), `homes Install Parameter「${name}」不得在契約欄位「${field}」指定 NAS 實體路徑或預設值。`, `請保留 install.${name}.type: homes，Compose 只引用 \${${name}}；由套件 在安裝時依這台 NAS 的 User Home 設定解析路徑。`));
         }
         if (isPosixAllSharesType(type)) {
             const configuredValue = Object.entries(param).find(([key, value]) => key !== "type" && (key === "default" || value !== undefined));
@@ -132,7 +155,7 @@ function validateInstallParameters(parsed, contractFile) {
                 const pos = getValuePosition(doc, ["install", name, field]) ??
                     getValuePosition(doc, ["install", name]) ??
                     { line: 1, column: 1 };
-                errors.push(makeError("CONTRACT_POSIX_ALL_SHARES_VALUE_FORBIDDEN", contractSpan(contractFile, pos.line, pos.column, `${basePath}.${field}`), `POSIX all-shares Install Parameter「${name}」不得指定 default 或 NAS 實體路徑；Share 清單只在安裝時由 Broker 透過 DSM API snapshot。`, `請只保留 install.${name}.type: posix_all_shares，Compose 使用 \${${name}} 作為完整 volume source。`));
+                errors.push(makeError("CONTRACT_POSIX_ALL_SHARES_VALUE_FORBIDDEN", contractSpan(contractFile, pos.line, pos.column, `${basePath}.${field}`), `POSIX all-shares Install Parameter「${name}」不得指定 default 或 NAS 實體路徑；Share 清單只在安裝時由 CLI 透過 DSM API 取得快照。`, `請只保留 install.${name}.type: posix_all_shares，Compose 使用 \${${name}} 作為完整 volume source。`));
             }
         }
     }

package/dist/contract/web-launch.js

@@ -81,8 +81,6 @@ export function renderWebStationResource(contract) {
     const alias = webStationAlias(String(contract.package));
     const launch = resolvedWebLaunch(contract);
     // DSM synowebapi crashes on type=reverse_proxy. Package acquire of reverse_proxy
-    // also creates a preserve portal that Broker cannot rebind (error 1300).
-    // Static + alias matches Broker; cookie strip / proxy_pass live in nginx user.conf.
     const service = {
         service: webStationServiceName(alias),
         display_name: String(contract.displayname ?? contract.package),

package/dist/deploy/deploy.d.ts

@@ -2,16 +2,13 @@ import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
 import type { ProjectRoot } from "../discovery.js";
 import type { NasHost } from "../host/types.js";
 import { resolveDeploySpkVersion } from "./spk-version.js";
-import type { PublishSpkResult } from "@synopackageland/package-source/publish-spk";
 export interface DeployProjectOptions {
     project: ProjectRoot;
     /** native App only: which target to build. Omitted means "ask the NAS". */
     archFamily?: NativeArchFamily;
     host: NasHost;
     dev?: boolean;
-    replaceCurated?: boolean;
     spkVersionResolver?: typeof resolveDeploySpkVersion;
-    catalogPublish?: (spkPath: string) => Promise<PublishSpkResult>;
     shareValues?: Record<string, string>;
     runAsValues?: Record<string, string>;
     paramValues?: Record<string, string>;
@@ -23,7 +20,7 @@ export interface DeployProjectResult {
     packageId?: string;
     spkPath?: string;
     openUrl?: string;
-    catalogVersion?: string;
+    version?: string;
     /** Non-blocking pre-flight remarks, e.g. a read-only Shared Folder grant. */
     notes?: string[];
 }

package/dist/deploy/deploy.js

@@ -1,10 +1,9 @@
 import { buildSpk } from "../build-spk/generator.js";
 import { existsSync } from "node:fs";
 import { loadContract } from "../contract/load.js";
-import { digestProjectBundle, digestProjectContract } from "../host/digests.js";
+import { findUnsupportedInstallTypes } from "../contract/unsupported-types.js";
 import { appOriginFromContract } from "../host/open-url.js";
 import { validateProject } from "../validate.js";
-import { publishBuiltSpk, packageSourceOrigin } from "./catalog-publish.js";
 import { resolveDeployIdentity, PACKAGE_IDENTITY_MAX_LENGTH } from "./identity.js";
 import { resolveDeploySpkVersion } from "./spk-version.js";
 import { resolveSharedFolderExtraValues, sharedFolderParameterNames } from "./share-values.js";
@@ -12,43 +11,26 @@ import { resolveDsmUserExtraValues, dsmUserParameterNames } from "./run-as-value
 import { runSharePermissionPreflight } from "./share-permission-preflight.js";
 import { homesParameterNames, resolveHomesExtraValues } from "./homes-values.js";
 import { resolveInstallParameterExtraValues } from "./param-values.js";
-import { CURATED_BUILD_OFFSET } from "@synopackageland/package-source/index-manifest";
-const CURATED_DEPLOY_REFUSED_MESSAGE = "此 NAS 已持有 Curated App Package Attestation。請改用 --dev，或使用 --replace-curated 明確降級。";
+import { loadCompose } from "../compose/analyze.js";
+import { runPortPreflight } from "./port-preflight.js";
 const POSIX_ALL_SHARES_LOOKUP_FAILED = "DEPLOY_POSIX_ALL_SHARES_LOOKUP_FAILED";
-function brokerCapabilitiesFromContract(project) {
-    const contract = loadContract(project.contractPath).contract;
-    const capabilities = ["identity"];
-    const integration = contract.integration;
-    if (integration?.files) {
-        capabilities.push("files");
-    }
-    return capabilities;
-}
-function versionBuildIsCurated(version) {
-    if (!version) {
-        return false;
-    }
-    const match = /-(\d+)$/.exec(version);
-    if (!match) {
-        return false;
-    }
-    const build = Number(match[1]);
-    return Number.isSafeInteger(build) && build >= CURATED_BUILD_OFFSET;
-}
-async function detectCuratedInstall(host, packageId) {
-    let brokerRecord = false;
-    try {
-        brokerRecord = (await host.getAttestationInfo(packageId)).attestationKind === "app-package";
-    }
-    catch {
-        // requestAttestation below remains the authoritative error path when the Broker info probe is unavailable.
-    }
-    return {
-        brokerRecord,
-        installedVersion: await host.getInstalledPackageVersion?.(packageId),
-    };
-}
 export async function deployProject(options) {
+    const contract = loadContract(options.project.contractPath).contract;
+    // A45/A46: refuse before anything is built or uploaded. validate only warns,
+    // so this is the gate that keeps an uninstallable App off a NAS.
+    const unsupported = findUnsupportedInstallTypes(contract);
+    if (unsupported.length > 0) {
+        const first = unsupported[0];
+        return {
+            ok: false,
+            code: first.code,
+            message: `Install Parameter「${first.name}」的 type: ${first.type} 目前沒有可用的安裝路徑，` +
+                "Package Center 安裝會以 DSM broken／150 結束，因此 deploy 拒絕部署。" +
+                (first.type === "homes"
+                    ? "若需要管理員選定的資料夾，請改用 type: shared_folder。"
+                    : "請改用 type: string，或讓 App 自行從 ${SYNO_APP_SECRETS_DIR} 讀檔。"),
+        };
+    }
     const validation = validateProject(options.project);
     if (!validation.ok) {
         return { ok: false, code: "VALIDATION_FAILED", message: validation.errors.map((e) => e.code).join(", ") };
@@ -61,14 +43,8 @@ export async function deployProject(options) {
             message: `最終 Package Identity「${identity.packageId}」長度 ${identity.packageId.length} 超過 DSM 上限 ${PACKAGE_IDENTITY_MAX_LENGTH} 字元。`,
         };
     }
-    const curatedInstall = identity.developmentInstance
-        ? undefined
-        : await detectCuratedInstall(options.host, identity.packageId);
-    const hasCuratedInstall = curatedInstall?.brokerRecord === true || versionBuildIsCurated(curatedInstall?.installedVersion);
-    if (hasCuratedInstall && !options.replaceCurated) {
-        return { ok: false, code: "CURATED_DEPLOY_REFUSED", message: CURATED_DEPLOY_REFUSED_MESSAGE };
-    }
-    const contract = loadContract(options.project.contractPath).contract;
+    const packageInstalled = await options.host.isPackageInstalled(identity.packageId);
+    const explicitParamNames = new Set(Object.keys(options.paramValues ?? {}));
     const paramValues = { ...(options.paramValues ?? {}) };
     const posixAllSharesNames = Object.entries(contract.install ?? {})
         .filter(([, parameter]) => parameter?.type === "posix_all_shares")
@@ -109,18 +85,16 @@ export async function deployProject(options) {
         return { ok: false, code: homesResolved.code, message: homesResolved.message };
     }
     const shareResolved = await resolveSharedFolderExtraValues({
-        requiredKeys: sharedFolderParameterNames(contract),
+        requiredKeys: sharedFolderParameterNames(contract).filter((key) => !packageInstalled || options.shareValues?.[key] !== undefined),
         provided: options.shareValues ?? {},
-        existingEnv: (await options.host.getInstalledProjectEnv?.(identity.packageId)) ?? {},
         lookup: async (logicalName) => options.host.resolveSharePath?.(logicalName),
     });
     if (!shareResolved.ok) {
         return { ok: false, code: shareResolved.code, message: shareResolved.message };
     }
     const runAsResolved = resolveDsmUserExtraValues({
-        requiredKeys: dsmUserParameterNames(contract),
+        requiredKeys: dsmUserParameterNames(contract).filter((key) => !packageInstalled || options.runAsValues?.[key] !== undefined),
         provided: options.runAsValues ?? {},
-        existingEnv: (await options.host.getInstalledProjectEnv?.(identity.packageId)) ?? {},
     });
     if (!runAsResolved.ok) {
         return { ok: false, code: runAsResolved.code, message: runAsResolved.message };
@@ -143,76 +117,45 @@ export async function deployProject(options) {
     if (!sharePermission.ok) {
         return { ok: false, code: sharePermission.code, message: sharePermission.message };
     }
+    const portPreflight = await runPortPreflight({
+        compose: loadCompose(options.project.composePath)?.compose,
+        packageIdentity: identity.packageId,
+        listPortInfo: options.host.listPortInfo
+            ? () => options.host.listPortInfo()
+            : undefined,
+    });
+    if (!portPreflight.ok) {
+        return { ok: false, code: portPreflight.code, message: portPreflight.message };
+    }
     const extraValues = {
         ...paramResolved.extraValues,
         ...homesResolved.extraValues,
         ...shareResolved.extraValues,
         ...runAsResolved.extraValues,
     };
-    const contractDigest = digestProjectContract(options.project);
-    const bundleDigest = digestProjectBundle(options.project);
-    if (hasCuratedInstall && options.replaceCurated) {
-        const installed = await options.host.isPackageInstalled(identity.packageId);
-        if (installed) {
-            console.warn("警告：--replace-curated 會移除 Curated 安裝，但會保留 App Data。");
-            if (!options.host.uninstallPackage) {
-                return {
-                    ok: false,
-                    code: "CATALOG_INSTALL_FAILED",
-                    message: "此 NAS Host 不支援保留 App Data 的 Curated replacement uninstall。",
-                };
-            }
-            try {
-                await options.host.uninstallPackage(identity.packageId);
+    // The upgrade wizard deliberately ignores auto-filled Share controls unless
+    // the administrator opted into a change. Keep the CLI's explicit upgrade
+    // flags equivalent to checking those controls.
+    if (packageInstalled) {
+        for (const name of sharedFolderParameterNames(contract)) {
+            if ((options.shareValues?.[name] ?? "").trim() !== "") {
+                extraValues[`CHANGE_${name}`] = "true";
             }
-            catch (error) {
-                return {
-                    ok: false,
-                    code: "CATALOG_INSTALL_FAILED",
-                    message: error instanceof Error ? error.message : String(error),
-                };
+        }
+        for (const name of posixAllSharesNames) {
+            if (explicitParamNames.has(name) && (paramValues[name] ?? "").trim() !== "") {
+                extraValues[`CHANGE_${name}`] = "true";
             }
         }
     }
-    let attestationResult;
-    try {
-        attestationResult = await options.host.requestAttestation({
-            packageIdentity: identity.packageId,
-            contractDigest,
-            bundleDigest,
-            capabilities: brokerCapabilitiesFromContract(options.project),
-            allowCuratedDowngrade: options.replaceCurated,
-        });
-    }
-    catch (error) {
-        const code = error.code ?? "ATTESTATION_FAILED";
-        return {
-            ok: false,
-            code,
-            message: code === "CURATED_DEPLOY_REFUSED"
-                ? CURATED_DEPLOY_REFUSED_MESSAGE
-                : error instanceof Error
-                    ? error.message
-                    : String(error),
-        };
-    }
     const resolveSpkVersion = options.spkVersionResolver ?? resolveDeploySpkVersion;
     let spkVersion;
     try {
         spkVersion = await resolveSpkVersion(options.project, options.host, identity.packageId);
     }
     catch (error) {
-        const code = error.code;
-        if (code === "DEPLOY_PERSONAL_BUILD_EXHAUSTED" ||
-            code === "PERSONAL_BUILD_EXHAUSTED" ||
-            code === "DEPLOY_VERSION_NOT_ASCENDING") {
-            return {
-                ok: false,
-                code: code === "DEPLOY_VERSION_NOT_ASCENDING" ? code : "DEPLOY_PERSONAL_BUILD_EXHAUSTED",
-                message: error instanceof Error ? error.message : String(error),
-            };
-        }
-        throw error;
+        return { ok: false, code: "DEPLOY_VERSION_INVALID",
+            message: error instanceof Error ? error.message : String(error) };
     }
     let archFamily = options.archFamily;
     if (archFamily === undefined && options.project.nativePath && existsSync(options.project.nativePath)) {
@@ -231,67 +174,25 @@ export async function deployProject(options) {
         displayname: identity.displayname,
         spkVersion,
         archFamily,
-        embeddedAttestationToken: attestationResult.token,
     });
     if (!build.ok || !build.outputPath) {
         return { ok: false, code: "BUILD_SPK_FAILED", message: build.errors.join(", ") };
     }
-    let catalogVersion = spkVersion;
-    const publishToCatalog = options.catalogPublish ?? publishBuiltSpk;
-    if (options.host.installationId === "live-nas" && !identity.developmentInstance) {
-        try {
-            const published = await publishToCatalog(build.outputPath);
-            catalogVersion = published.version;
-        }
-        catch (error) {
-            return {
-                ok: false,
-                code: "CATALOG_PUBLISH_FAILED",
-                message: error instanceof Error ? error.message : String(error),
-            };
-        }
-    }
     try {
-        if (identity.developmentInstance) {
-            if (!options.host.installFromLocalSpk) {
-                return {
-                    ok: false,
-                    code: "LOCAL_SPK_INSTALL_UNSUPPORTED",
-                    message: "Development deploy requires installFromLocalSpk on the host adapter.",
-                };
-            }
-            await options.host.installFromLocalSpk({
-                packageId: identity.packageId,
-                version: catalogVersion,
-                spkPath: build.outputPath,
-                extraValues,
-            });
-        }
-        else {
-            if (options.host.ensurePackageSource) {
-                await options.host.ensurePackageSource(packageSourceOrigin());
-            }
-            await options.host.installFromCatalog({
-                packageId: identity.packageId,
-                version: catalogVersion,
-                extraValues,
-            });
-        }
+        await options.host.installFromLocalSpk({
+            packageId: identity.packageId,
+            version: spkVersion,
+            spkPath: build.outputPath,
+            extraValues,
+        });
     }
     catch (error) {
-        return {
-            ok: false,
-            code: "CATALOG_INSTALL_FAILED",
-            message: error instanceof Error ? error.message : String(error),
-        };
+        return { ok: false, code: "LOCAL_SPK_INSTALL_FAILED",
+            message: error instanceof Error ? error.message : String(error) };
     }
-    const info = await options.host.getAttestationInfo(identity.packageId);
     return {
-        ok: true,
-        packageId: identity.packageId,
-        spkPath: build.outputPath,
-        openUrl: info.openUrl ?? appOriginFromContract(options.host.dsmOrigin, contract),
-        catalogVersion,
-        notes: sharePermission.notes.length > 0 ? sharePermission.notes : undefined,
+        ok: true, packageId: identity.packageId, spkPath: build.outputPath,
+        openUrl: appOriginFromContract(options.host.dsmOrigin, contract),
+        version: spkVersion, notes: sharePermission.notes,
     };
 }

package/dist/deploy/homes-values.js

@@ -19,7 +19,7 @@ export async function resolveHomesExtraValues(input) {
         return {
             ok: false,
             code: "HOMES_NOT_ENABLED",
-            message: "這台 NAS 未啟用 DSM User Home，或 Broker 無法解析 user home 路徑；無法安裝需要 homes 的 App。請在 DSM 啟用 User Home 後重試。",
+            message: "這台 NAS 未啟用 DSM User Home，或 DSM API 無法解析 user home 路徑；無法安裝需要 homes 的 App。請在 DSM 啟用 User Home 後重試。",
         };
     }
     return {

package/dist/deploy/plan.d.ts

@@ -0,0 +1,18 @@
+import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
+import type { NasHost } from "../host/types.js";
+export interface DeploymentPlan {
+    root: string;
+    kind: "native-go" | "binary" | "container";
+    packageId: string;
+    version: string;
+    arch?: NativeArchFamily;
+    privilege: "none" | "root";
+    transport: "dsm-local-spk";
+    notes: string[];
+}
+/** Purely local planning: no credentials, network, build or installation. */
+export declare function planDeployment(root: string, options?: {
+    arch?: NativeArchFamily;
+    dev?: boolean;
+}): DeploymentPlan;
+export declare function deployStandalone(plan: DeploymentPlan, host: NasHost): Promise<string>;

package/dist/deploy/plan.js

@@ -0,0 +1,54 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { findProjectRoot } from "../discovery.js";
+import { loadContract } from "../contract/load.js";
+import { validateProject } from "../validate.js";
+import { findStandaloneRoot, loadStandaloneManifest } from "../standalone/manifest.js";
+import { buildStandalone } from "../standalone/build.js";
+import { resolveDeployIdentity } from "./identity.js";
+import { nextDeployVersion } from "./spk-version.js";
+/** Purely local planning: no credentials, network, build or installation. */
+export function planDeployment(root, options = {}) {
+    const standalone = findStandaloneRoot(root);
+    if (standalone) {
+        const loaded = loadStandaloneManifest(standalone);
+        if (!loaded.ok)
+            throw new Error(loaded.errors.map(e => `${e.code}: ${e.message}`).join("\n"));
+        const m = loaded.manifest;
+        if (options.dev)
+            throw new Error('--dev is not supported for native-go; choose a distinct package name at init');
+        if (options.arch && !m.arches.includes(options.arch))
+            throw new Error(`Architecture not declared: ${options.arch}`);
+        return { root: standalone, kind: "native-go", packageId: m.package, version: m.spkVersion,
+            arch: options.arch, privilege: m.privilege, transport: "dsm-local-spk",
+            notes: m.privilege === "root" ? ['Approve root tasks in DSM after installation; changed task text requires fresh approval. Remove tasks before uninstall.'] : [] };
+    }
+    const project = findProjectRoot(root);
+    if (!project)
+        throw new Error('No dsm-package.yaml or synology-app.yaml found');
+    const validation = validateProject(project);
+    if (!validation.ok)
+        throw new Error(validation.errors.map(e => `${e.code}: ${e.message}`).join("\n"));
+    const contract = loadContract(project.contractPath).contract;
+    const identity = resolveDeployIdentity(project, { dev: options.dev });
+    return { root: project.root, kind: existsSync(join(project.root, 'native.yaml')) ? 'binary' : 'container',
+        packageId: identity.packageId, version: nextDeployVersion(String(contract.version)),
+        arch: options.arch, privilege: 'none', transport: 'dsm-local-spk',
+        notes: ['DSM resolves target architecture and installed version during deployment. Container bind access uses the configured process user.'] };
+}
+export async function deployStandalone(plan, host) {
+    if (plan.kind !== 'native-go')
+        throw new Error('Expected native-go deployment plan');
+    const arch = plan.arch ?? await host.getArchFamily?.();
+    if (!arch)
+        throw new Error('Cannot determine NAS architecture; specify --arch');
+    const installed = await host.getInstalledPackageVersion?.(plan.packageId);
+    if (installed && nextDeployVersion(plan.version, installed) !== plan.version) {
+        throw new Error(`Increase dsm-package.yaml version/build above installed ${installed}`);
+    }
+    const { outputs } = await buildStandalone({ root: plan.root, arches: [arch] });
+    if (outputs.length !== 1)
+        throw new Error('Expected one SPK');
+    await host.installFromLocalSpk({ packageId: plan.packageId, version: plan.version, spkPath: outputs[0] });
+    return outputs[0];
+}

package/dist/deploy/port-preflight.d.ts

@@ -0,0 +1,21 @@
+import type { ComposeDocument } from "../types.js";
+import { type PortInfoEntry } from "../host/port-info.js";
+export declare const PORT_ALREADY_IN_USE = "PORT_ALREADY_IN_USE";
+export interface PortPreflightInput {
+    compose?: ComposeDocument;
+    packageIdentity: string;
+    listPortInfo?: () => Promise<PortInfoEntry[] | undefined>;
+}
+export type PortPreflightResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: typeof PORT_ALREADY_IN_USE;
+    message: string;
+};
+/**
+ * Checks Compose's published TCP host ports against DSM's administrator-only
+ * PortInfo listing. Missing capability, transport failure, malformed data,
+ * and an empty listing all mean "cannot tell" and therefore pass through.
+ */
+export declare function runPortPreflight(input: PortPreflightInput): Promise<PortPreflightResult>;

package/dist/deploy/port-preflight.js

@@ -0,0 +1,42 @@
+import { collectPublishedTcpPorts } from "../compose/analyze.js";
+import { findPortConflicts, formatPortOccupant, } from "../host/port-info.js";
+export const PORT_ALREADY_IN_USE = "PORT_ALREADY_IN_USE";
+/**
+ * Checks Compose's published TCP host ports against DSM's administrator-only
+ * PortInfo listing. Missing capability, transport failure, malformed data,
+ * and an empty listing all mean "cannot tell" and therefore pass through.
+ */
+export async function runPortPreflight(input) {
+    const publishedPorts = input.compose
+        ? collectPublishedTcpPorts(input.compose)
+        : new Map();
+    if (publishedPorts.size === 0 || !input.listPortInfo) {
+        return { ok: true };
+    }
+    let portInfo;
+    try {
+        portInfo = await input.listPortInfo();
+    }
+    catch {
+        portInfo = undefined;
+    }
+    if (!portInfo || portInfo.length === 0) {
+        return { ok: true };
+    }
+    const conflicts = findPortConflicts({
+        publishedPorts,
+        packageIdentity: input.packageIdentity,
+        portInfo,
+    });
+    const conflict = conflicts[0];
+    if (!conflict) {
+        return { ok: true };
+    }
+    const occupants = conflict.occupants.map(formatPortOccupant).join("、");
+    return {
+        ok: false,
+        code: PORT_ALREADY_IN_USE,
+        message: `Published port ${conflict.port} 已被 ${occupants} 佔用（Compose service：${conflict.services.join("、")}）。` +
+            "請改用未被其他服務使用的 host port；同一 Package Identity 的既有容器會在升級／重裝時放行。",
+    };
+}

package/dist/deploy/spk-version.d.ts

@@ -1,17 +1,5 @@
 import type { ProjectRoot } from "../discovery.js";
 import type { NasHost } from "../host/types.js";
-export declare class DeployPersonalBuildExhaustedError extends Error {
-    readonly code = "DEPLOY_PERSONAL_BUILD_EXHAUSTED";
-    constructor();
-}
-export declare class DeployVersionNotAscendingError extends Error {
-    readonly code = "DEPLOY_VERSION_NOT_ASCENDING";
-    constructor(contractVersion: string, proposedVersion: string, existingVersion: string);
-}
-export interface DeployVersionCandidates {
-    installed?: string;
-    feed?: string;
-}
-export declare function resolvePersonalDeploySpkVersion(contractVersion: string, candidates?: DeployVersionCandidates): string;
+/** Increment the installed build only for the same application version. */
+export declare function nextDeployVersion(version: string, installed?: string): string;
 export declare function resolveDeploySpkVersion(project: ProjectRoot, host: NasHost, packageId: string): Promise<string>;
-export declare function publishDeploySpk(spkPath: string): Promise<string>;