@synopackageland/cli 0.3.1 → 0.3.2

package/dist/contract/posix-all-shares.js

@@ -0,0 +1,63 @@
+import { composeSpan, makeError } from "../errors.js";
+/** Install type for a deliberate, install-time snapshot of every DSM Share. */
+export const POSIX_ALL_SHARES_TYPE = "posix_all_shares";
+/** Reserved names keep an undeclared all-shares marker diagnosable. */
+const RESERVED_MARKER_NAMES = new Set(["ALL_SHARES", "POSIX_ALL_SHARES"]);
+const INTERPOLATED_SOURCE = /^\$\{([A-Z0-9_]+)\}(.*)$/;
+export function isPosixAllSharesType(type) {
+    return type === POSIX_ALL_SHARES_TYPE;
+}
+export function collectPosixAllSharesParameters(installParams) {
+    return new Set(installParams.filter(({ param }) => isPosixAllSharesType(param.type)).map(({ name }) => name));
+}
+/**
+ * Validate the extra semantics of the all-shares marker without changing the
+ * shared host-bind analyzer. The latter is intentionally left as the single
+ * authority for absolute paths, suffix syntax, and named volumes.
+ */
+export function validatePosixAllSharesSources(compose, composeFile, declaredParameters) {
+    const errors = [];
+    if (!compose.services || typeof compose.services !== "object") {
+        return errors;
+    }
+    for (const [serviceName, service] of Object.entries(compose.services)) {
+        const entries = Array.isArray(service?.volumes)
+            ? service.volumes
+            : service?.volumes === undefined
+                ? []
+                : [service.volumes];
+        for (let index = 0; index < entries.length; index += 1) {
+            const source = volumeSource(entries[index]);
+            if (!source) {
+                continue;
+            }
+            const match = source.match(INTERPOLATED_SOURCE);
+            if (!match) {
+                continue;
+            }
+            const [, name, suffix] = match;
+            const path = `services.${serviceName}.volumes.${index}`;
+            if (declaredParameters.has(name)) {
+                if (suffix !== "") {
+                    errors.push(makeError("COMPOSE_POSIX_ALL_SHARES_SUFFIX_FORBIDDEN", composeSpan(composeFile, 1, 1, path), `POSIX all-shares 參數「${name}」只能作為完整 volume source，不能附加子路徑。`, `請將 ${source} 改成 \${${name}}，並保留 Compose 的 container target；Share 名稱由 Broker 在安裝時展開。`));
+                }
+                continue;
+            }
+            if (RESERVED_MARKER_NAMES.has(name)) {
+                errors.push(makeError("COMPOSE_POSIX_ALL_SHARES_UNDECLARED", composeSpan(composeFile, 1, 1, path), `Compose 使用了未宣告的 POSIX all-shares marker「${name}」。`, `請在 synology-app.yaml 宣告 install.${name}.type: ${POSIX_ALL_SHARES_TYPE}，並讓 Broker 以 DSM API 列出安裝當下的 Share。`));
+            }
+        }
+    }
+    return errors;
+}
+function volumeSource(entry) {
+    if (typeof entry === "string") {
+        const colon = entry.indexOf(":");
+        return colon > 0 ? entry.slice(0, colon).trim() : undefined;
+    }
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return undefined;
+    }
+    const source = entry.source;
+    return typeof source === "string" && source.trim() ? source.trim() : undefined;
+}

package/dist/contract/schema-validate.js

@@ -30,7 +30,7 @@ function mapSchemaError(error, contractFile, parsed) {
 }
 export function validateContractSchema(parsed, contractFile) {
     const validate = getValidator();
-    const data = parsed.doc.toJSON();
+    const data = schemaCompatibleContract(parsed.doc.toJSON());
     const valid = validate(data);
     if (valid) {
         return [];
@@ -48,3 +48,28 @@ export function validateContractSchema(parsed, contractFile) {
     }
     return result;
 }
+/**
+ * Keep the published v1 schema's historical enum stable for older tooling,
+ * while allowing the P4 contract extension to be validated by the same v1
+ * object shape. The semantic validator and Broker retain the raw type.
+ */
+function schemaCompatibleContract(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return value;
+    }
+    const contract = value;
+    const install = contract.install;
+    if (!install || typeof install !== "object" || Array.isArray(install)) {
+        return value;
+    }
+    for (const parameter of Object.values(install)) {
+        if (!parameter || typeof parameter !== "object" || Array.isArray(parameter)) {
+            continue;
+        }
+        const record = parameter;
+        if (record.type === "posix_all_shares") {
+            record.type = "homes";
+        }
+    }
+    return value;
+}

package/dist/contract/validate.js

@@ -1,7 +1,11 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { contractSpan, makeError } from "../errors.js";
 import { collectInstallParameters, getValuePosition, stringViolations, } from "./load.js";
 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";
 /** DSM 7.4 Package Center rejects a longer package identity outright. */
 const DSM_PACKAGE_IDENTITY_MAX = 32;
 const METADATA_STRING_FIELDS = [
@@ -38,9 +42,36 @@ export function validateContract(parsed, contractFile) {
         }
     }
     errors.push(...validateInstallParameters(parsed, contractFile));
+    errors.push(...validatePosixAllShares(parsed, contractFile));
     errors.push(...validateWebLaunch(parsed, contractFile));
+    // The P4 worker cannot edit the shared host-bind analyzer. Its existing
+    // platform-resolved `homes` slot has the same analyzer semantics (declared
+    // interpolation is an allowed source and must be used). This normalization
+    // is local to the validation object; Broker and SPK generation read the raw
+    // YAML again and retain the actual posix_all_shares type.
+    for (const parameter of Object.values(contract.install ?? {})) {
+        if (parameter && isPosixAllSharesType(parameter.type)) {
+            parameter.type = "homes";
+        }
+    }
     return errors;
 }
+function validatePosixAllShares(parsed, contractFile) {
+    const contractPath = parsed.contractPath;
+    if (!contractPath) {
+        return [];
+    }
+    const composePath = join(dirname(contractPath), "compose.yaml");
+    if (!existsSync(composePath)) {
+        return [];
+    }
+    const parsedCompose = loadCompose(composePath);
+    if (!parsedCompose) {
+        return [];
+    }
+    const parameters = collectPosixAllSharesParameters(collectInstallParameters(parsed.contract));
+    return validatePosixAllSharesSources(parsedCompose.compose, contractFile, parameters);
+}
 function validateWebLaunch(parsed, contractFile) {
     const errors = [];
     const { contract, doc } = parsed;
@@ -85,6 +116,32 @@ function validateInstallParameters(parsed, contractFile) {
                 errors.push(makeError("INSTALL_STRING_INVALID", contractSpan(contractFile, pos.line, pos.column, `${basePath}.default`), `Install Parameter「${name}」的字串值不合法。`, "請移除控制字元與 ${ 插值語法。"));
             }
         }
+        if (type === "homes") {
+            const configuredPath = Object.entries(param).find(([key, value]) => key !== "type" &&
+                (key === "default" || (typeof value === "string" && isPhysicalHostPath(value))));
+            if (!configuredPath) {
+                continue;
+            }
+            const [field] = configuredPath;
+            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 設定解析路徑。`));
+        }
+        if (isPosixAllSharesType(type)) {
+            const configuredValue = Object.entries(param).find(([key, value]) => key !== "type" && (key === "default" || value !== undefined));
+            if (configuredValue) {
+                const [field] = configuredValue;
+                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。`));
+            }
+        }
     }
     return errors;
 }
+function isPhysicalHostPath(value) {
+    const trimmed = value.trim();
+    return trimmed.startsWith("/") || /(?:^|\/)volume(?:USB|SATA)?\d+/i.test(trimmed);
+}

package/dist/contract/web-launch.d.ts

@@ -13,6 +13,12 @@ export declare function isWebLaunchMode(value: unknown): value is WebLaunchMode;
 export declare function resolvedWebLaunch(contract: AppContract): WebLaunchMode | undefined;
 export declare function webStationAlias(packageId: string): string;
 export declare function trustedAppEntryPath(contract: AppContract): string;
+export declare const DSM_RESERVED_COOKIES: readonly ["id", "did"];
+export declare function extractContractCookieNames(contract: AppContract): string[];
+export declare function cookieStripHeaders(contract: AppContract): Array<{
+    name: string;
+    value: string;
+}>;
 export declare function webStationServiceName(alias: string): string;
 export declare function webStationServiceRoot(alias: string): string;
 export declare function renderWebStationResource(contract: AppContract): string;

package/dist/contract/web-launch.js

@@ -46,6 +46,31 @@ export function trustedAppEntryPath(contract) {
     }
     return `/${alias}${extra}`;
 }
+export const DSM_RESERVED_COOKIES = ["id", "did"];
+export function extractContractCookieNames(contract) {
+    const web = readWebIntegration(contract);
+    if (!web || !Array.isArray(web.cookies)) {
+        return [];
+    }
+    const reserved = new Set(DSM_RESERVED_COOKIES);
+    const result = [];
+    for (const item of web.cookies) {
+        if (typeof item === "string") {
+            const name = item.trim();
+            if (name && !reserved.has(name) && !result.includes(name)) {
+                result.push(name);
+            }
+        }
+    }
+    return result;
+}
+export function cookieStripHeaders(contract) {
+    const names = extractContractCookieNames(contract);
+    const value = names.length > 0
+        ? names.map((name) => `${name}=$cookie_${name}`).join("; ")
+        : "_synopkgland=";
+    return [{ name: "Cookie", value }];
+}
 export function webStationServiceName(alias) {
     return `PROXY-${alias}`;
 }

package/dist/deploy/deploy.d.ts

@@ -14,6 +14,7 @@ export interface DeployProjectOptions {
     catalogPublish?: (spkPath: string) => Promise<PublishSpkResult>;
     shareValues?: Record<string, string>;
     runAsValues?: Record<string, string>;
+    paramValues?: Record<string, string>;
 }
 export interface DeployProjectResult {
     ok: boolean;

package/dist/deploy/deploy.js

@@ -9,6 +9,8 @@ import { resolveDeployIdentity } from "./identity.js";
 import { resolveDeploySpkVersion } from "./spk-version.js";
 import { resolveSharedFolderExtraValues, sharedFolderParameterNames } from "./share-values.js";
 import { resolveDsmUserExtraValues, dsmUserParameterNames } from "./run-as-values.js";
+import { homesParameterNames, resolveHomesExtraValues } from "./homes-values.js";
+import { resolveInstallParameterExtraValues } from "./param-values.js";
 const CURATED_DEPLOY_REFUSED_MESSAGE = "此 NAS 已持有 Curated App Package Attestation。請改用 --dev，或使用 --replace-curated 明確降級。";
 function brokerCapabilitiesFromContract(project) {
     const contract = loadContract(project.contractPath).contract;
@@ -26,6 +28,20 @@ export async function deployProject(options) {
     }
     const identity = resolveDeployIdentity(options.project, { dev: options.dev });
     const contract = loadContract(options.project.contractPath).contract;
+    const paramResolved = resolveInstallParameterExtraValues({
+        contract,
+        provided: options.paramValues,
+    });
+    if (!paramResolved.ok) {
+        return { ok: false, code: paramResolved.code, message: paramResolved.message };
+    }
+    const homesResolved = await resolveHomesExtraValues({
+        requiredKeys: homesParameterNames(contract),
+        lookup: async () => options.host.resolveHomesPath?.(),
+    });
+    if (!homesResolved.ok) {
+        return { ok: false, code: homesResolved.code, message: homesResolved.message };
+    }
     const shareResolved = await resolveSharedFolderExtraValues({
         requiredKeys: sharedFolderParameterNames(contract),
         provided: options.shareValues ?? {},
@@ -43,7 +59,12 @@ export async function deployProject(options) {
     if (!runAsResolved.ok) {
         return { ok: false, code: runAsResolved.code, message: runAsResolved.message };
     }
-    const extraValues = { ...shareResolved.extraValues, ...runAsResolved.extraValues };
+    const extraValues = {
+        ...paramResolved.extraValues,
+        ...homesResolved.extraValues,
+        ...shareResolved.extraValues,
+        ...runAsResolved.extraValues,
+    };
     const contractDigest = digestProjectContract(options.project);
     const bundleDigest = digestProjectBundle(options.project);
     try {
@@ -68,7 +89,21 @@ export async function deployProject(options) {
         };
     }
     const resolveSpkVersion = options.spkVersionResolver ?? resolveDeploySpkVersion;
-    const spkVersion = await resolveSpkVersion(options.project, options.host, identity.packageId);
+    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") {
+            return {
+                ok: false,
+                code: "DEPLOY_PERSONAL_BUILD_EXHAUSTED",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        throw error;
+    }
     let archFamily = options.archFamily;
     if (archFamily === undefined && options.project.nativePath && existsSync(options.project.nativePath)) {
         archFamily = await options.host.getArchFamily?.();

package/dist/deploy/homes-values.d.ts

@@ -0,0 +1,19 @@
+import type { AppContract } from "../types.js";
+export declare const HOMES_NOT_ENABLED = "HOMES_NOT_ENABLED";
+export declare function homesParameterNames(contract: AppContract): string[];
+export type HomesResolveResult = {
+    ok: true;
+    extraValues: Record<string, string>;
+} | {
+    ok: false;
+    code: typeof HOMES_NOT_ENABLED;
+    message: string;
+};
+/**
+ * Resolve the platform's user-home root at deploy time. The contract only
+ * names a logical homes slot; the host adapter owns the NAS-specific lookup.
+ */
+export declare function resolveHomesExtraValues(input: {
+    requiredKeys: string[];
+    lookup: () => Promise<string | undefined>;
+}): Promise<HomesResolveResult>;

package/dist/deploy/homes-values.js

@@ -0,0 +1,29 @@
+import { collectInstallParameters } from "../contract/load.js";
+export const HOMES_NOT_ENABLED = "HOMES_NOT_ENABLED";
+export function homesParameterNames(contract) {
+    return collectInstallParameters(contract)
+        .filter((item) => item.param.type === "homes")
+        .map((item) => item.name);
+}
+/**
+ * Resolve the platform's user-home root at deploy time. The contract only
+ * names a logical homes slot; the host adapter owns the NAS-specific lookup.
+ */
+export async function resolveHomesExtraValues(input) {
+    if (input.requiredKeys.length === 0) {
+        return { ok: true, extraValues: {} };
+    }
+    const resolved = await input.lookup();
+    const path = resolved?.trim();
+    if (!path || !path.startsWith("/")) {
+        return {
+            ok: false,
+            code: "HOMES_NOT_ENABLED",
+            message: "這台 NAS 未啟用 DSM User Home，或 Broker 無法解析 user home 路徑；無法安裝需要 homes 的 App。請在 DSM 啟用 User Home 後重試。",
+        };
+    }
+    return {
+        ok: true,
+        extraValues: Object.fromEntries(input.requiredKeys.map((key) => [key, path])),
+    };
+}

package/dist/deploy/param-values.d.ts

@@ -0,0 +1,21 @@
+import type { AppContract } from "../types.js";
+export type InstallParameterResolveResult = {
+    ok: true;
+    extraValues: Record<string, string>;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Validate the local, non-secret values accepted by `deploy --param`.
+ *
+ * DSM's Installation/install `extra_values` is a string map. The classic
+ * wizard's boolean `multiselect` therefore crosses that boundary as the
+ * canonical text values `true` or `false`, which is also the representation
+ * consumed by the package-only materializer when it writes `.env`.
+ */
+export declare function resolveInstallParameterExtraValues(input: {
+    contract: AppContract;
+    provided?: Record<string, string>;
+}): InstallParameterResolveResult;

package/dist/deploy/param-values.js

@@ -0,0 +1,51 @@
+import { collectInstallParameters, stringViolations } from "../contract/load.js";
+/**
+ * Validate the local, non-secret values accepted by `deploy --param`.
+ *
+ * DSM's Installation/install `extra_values` is a string map. The classic
+ * wizard's boolean `multiselect` therefore crosses that boundary as the
+ * canonical text values `true` or `false`, which is also the representation
+ * consumed by the package-only materializer when it writes `.env`.
+ */
+export function resolveInstallParameterExtraValues(input) {
+    const declared = new Map(collectInstallParameters(input.contract).map(({ name, param }) => [name, param]));
+    const extraValues = {};
+    for (const [name, raw] of Object.entries(input.provided ?? {})) {
+        const param = declared.get(name);
+        if (!param) {
+            return {
+                ok: false,
+                code: "DEPLOY_PARAM_UNDECLARED",
+                message: `--param 提供了未宣告的 Install Parameter「${name}」。只接受 synology-app.yaml install 中宣告的 string/boolean 名稱。`,
+            };
+        }
+        if (param.type === "boolean") {
+            if (raw !== "true" && raw !== "false") {
+                return {
+                    ok: false,
+                    code: "DEPLOY_PARAM_TYPE_INVALID",
+                    message: `--param ${name}=... 必須是 boolean 的 true 或 false；DSM multiselect 會以這兩個字串交給 Installation/install。`,
+                };
+            }
+            extraValues[name] = raw;
+            continue;
+        }
+        if (param.type !== "string") {
+            return {
+                ok: false,
+                code: "DEPLOY_PARAM_TYPE_INVALID",
+                message: `--param ${name}=... 對應的契約型別是 ${String(param.type ?? "未指定")}；deploy --param 只接受 string/boolean。`,
+            };
+        }
+        const violations = stringViolations(raw);
+        if (raw.length === 0 || violations.hasControlChars || violations.hasInterpolation || violations.tooLong) {
+            return {
+                ok: false,
+                code: "DEPLOY_PARAM_TYPE_INVALID",
+                message: `--param ${name}=... 不符合 string Install Parameter 約束（不可空白、控制字元、\${ 插值或超過 256 字元）。`,
+            };
+        }
+        extraValues[name] = raw;
+    }
+    return { ok: true, extraValues };
+}

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

@@ -1,4 +1,9 @@
 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 function bumpBuildNumber(version: string): string;
 export declare function resolveDeploySpkVersion(project: ProjectRoot, host: NasHost, packageId: string): Promise<string>;
 export declare function publishDeploySpk(spkPath: string): Promise<string>;

package/dist/deploy/spk-version.js

@@ -1,19 +1,42 @@
 import { loadContract } from "../contract/load.js";
-import { comparePackageVersions } from "@synopackageland/package-source/index-manifest";
-import { resolveNextSpkVersion } from "@synopackageland/package-source/next-version";
+import { comparePackageVersions, CURATED_BUILD_OFFSET, PERSONAL_BUILD_MAX, } from "@synopackageland/package-source/index-manifest";
+import { PersonalBuildExhaustedError, resolveNextSpkVersion, } from "@synopackageland/package-source/next-version";
 import { fetchPackageSourceManifest, fetchPackageSourceManifestFromR2, resolvePublishTarget, } from "@synopackageland/package-source/publish-spk";
 import { publishBuiltSpk } from "./catalog-publish.js";
 import { isDevelopmentPackageIdentity } from "./identity-shared.js";
 const LIVE_TEST_FALLBACK_ORIGIN = "https://syno-package-source-throwaway.bidacumen.workers.dev";
+export class DeployPersonalBuildExhaustedError extends Error {
+    code = "DEPLOY_PERSONAL_BUILD_EXHAUSTED";
+    constructor() {
+        super(`Personal Package Build range exhausted at ${PERSONAL_BUILD_MAX}`);
+        this.name = "DeployPersonalBuildExhaustedError";
+    }
+}
 function defaultSpkVersion(contractVersion) {
-    return /-\d+$/.test(contractVersion) ? contractVersion : `${contractVersion}-0001`;
+    const match = /-(\d+)$/.exec(contractVersion);
+    if (!match) {
+        return `${contractVersion}-0001`;
+    }
+    const build = Number(match[1]);
+    if (!Number.isSafeInteger(build) || build >= CURATED_BUILD_OFFSET) {
+        throw new DeployPersonalBuildExhaustedError();
+    }
+    return contractVersion;
 }
-function bumpBuildNumber(version) {
+export function bumpBuildNumber(version) {
     const match = /^(.+)-(\d+)$/.exec(version);
     if (!match) {
         return `${version}-0002`;
     }
-    const next = String(Number(match[2]) + 1).padStart(4, "0");
+    const current = Number(match[2]);
+    if (!Number.isSafeInteger(current) || current >= CURATED_BUILD_OFFSET) {
+        throw new DeployPersonalBuildExhaustedError();
+    }
+    const nextBuild = current + 1;
+    if (nextBuild > PERSONAL_BUILD_MAX) {
+        throw new DeployPersonalBuildExhaustedError();
+    }
+    const next = String(nextBuild).padStart(4, "0");
     return `${match[1]}-${next}`;
 }
 async function resolvePackageSourceManifest(origin) {
@@ -41,22 +64,31 @@ async function resolveOfflineDeploySpkVersion(project, host, packageId) {
     return installed ? bumpBuildNumber(installed) : base;
 }
 export async function resolveDeploySpkVersion(project, host, packageId) {
-    if (host.installationId !== "live-nas" || isDevelopmentPackageIdentity(packageId)) {
-        return resolveOfflineDeploySpkVersion(project, host, packageId);
+    try {
+        if (host.installationId !== "live-nas" || isDevelopmentPackageIdentity(packageId)) {
+            return resolveOfflineDeploySpkVersion(project, host, packageId);
+        }
+        const contract = loadContract(project.contractPath).contract;
+        const target = resolvePublishTarget();
+        const manifest = (await fetchPackageSourceManifestFromR2(target)) ??
+            (await resolvePackageSourceManifest(target.origin));
+        let version = resolveNextSpkVersion(String(contract.version ?? "1.0.0"), packageId, manifest);
+        const installed = await host.getInstalledPackageVersion?.(packageId);
+        if (installed) {
+            const installedNext = bumpBuildNumber(installed);
+            if (comparePackageVersions(installedNext, version) > 0) {
+                version = installedNext;
+            }
+        }
+        return version;
     }
-    const contract = loadContract(project.contractPath).contract;
-    const target = resolvePublishTarget();
-    const manifest = (await fetchPackageSourceManifestFromR2(target)) ??
-        (await resolvePackageSourceManifest(target.origin));
-    let version = resolveNextSpkVersion(String(contract.version ?? "1.0.0"), packageId, manifest);
-    const installed = await host.getInstalledPackageVersion?.(packageId);
-    if (installed) {
-        const installedNext = bumpBuildNumber(installed);
-        if (comparePackageVersions(installedNext, version) > 0) {
-            version = installedNext;
+    catch (error) {
+        if (error instanceof PersonalBuildExhaustedError ||
+            error.code === "PERSONAL_BUILD_EXHAUSTED") {
+            throw new DeployPersonalBuildExhaustedError();
         }
+        throw error;
     }
-    return version;
 }
 export async function publishDeploySpk(spkPath) {
     const published = await publishBuiltSpk(spkPath);

package/dist/doctor.d.ts

@@ -0,0 +1,22 @@
+import type { ProjectRoot } from "./discovery.js";
+import type { NasHost } from "./host/types.js";
+export type DoctorCheckStatus = "pass" | "fail" | "skip";
+export interface DoctorCheck {
+    id: string;
+    status: DoctorCheckStatus;
+    code?: string;
+    message: string;
+    suggestion?: string;
+}
+export interface DoctorReport {
+    ok: boolean;
+    checks: DoctorCheck[];
+}
+export interface RunDoctorOptions {
+    project?: ProjectRoot | null;
+    host?: NasHost | null;
+    packageId?: string;
+    dev?: boolean;
+}
+export declare function runDoctor(options: RunDoctorOptions): Promise<DoctorReport>;
+export declare function formatDoctorReport(report: DoctorReport): string;