@synopackageland/cli 0.1.0

package/dist/contract/load.js

@@ -0,0 +1,87 @@
+import { readFileSync } from "node:fs";
+import { parseDocument, isMap, isScalar } from "yaml";
+export function loadContract(contractPath) {
+    const source = readFileSync(contractPath, "utf8");
+    const doc = parseDocument(source);
+    const contract = (doc.toJSON() ?? {});
+    return { contract, doc };
+}
+export function getScalarPosition(doc, keyPath) {
+    const node = findNode(doc.contents, keyPath);
+    if (!node || !isScalar(node.key)) {
+        return null;
+    }
+    const range = node.key.range;
+    if (!range) {
+        return { line: 1, column: 1 };
+    }
+    return lineColumnFromOffset(doc, range[0]);
+}
+export function getValuePosition(doc, keyPath) {
+    const node = findNode(doc.contents, keyPath);
+    if (!node) {
+        return null;
+    }
+    const valueNode = node.value;
+    const keyNode = node.key;
+    const range = valueNode?.range ?? keyNode?.range;
+    if (!range) {
+        return { line: 1, column: 1 };
+    }
+    return lineColumnFromOffset(doc, range[0]);
+}
+function findNode(node, keyPath) {
+    if (!node || keyPath.length === 0) {
+        return null;
+    }
+    const [head, ...rest] = keyPath;
+    if (!isMap(node)) {
+        return null;
+    }
+    for (const item of node.items) {
+        if (!isScalar(item.key) || String(item.key.value) !== head) {
+            continue;
+        }
+        if (rest.length === 0) {
+            return item;
+        }
+        return findNode(item.value, rest);
+    }
+    return null;
+}
+function lineColumnFromOffset(doc, offset) {
+    const source = String(doc.toString());
+    let line = 1;
+    let column = 1;
+    for (let i = 0; i < offset && i < source.length; i++) {
+        if (source[i] === "\n") {
+            line++;
+            column = 1;
+        }
+        else {
+            column++;
+        }
+    }
+    return { line, column };
+}
+export function collectInstallParameters(contract) {
+    if (!contract.install || typeof contract.install !== "object") {
+        return [];
+    }
+    return Object.entries(contract.install).map(([name, param]) => ({
+        name,
+        param: param ?? {},
+    }));
+}
+export function isDeveloperAuthoredString(value) {
+    return typeof value === "string";
+}
+const CONTROL_CHAR_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
+const INTERPOLATION_PATTERN = /\$\{/;
+export function stringViolations(value) {
+    return {
+        hasControlChars: CONTROL_CHAR_PATTERN.test(value),
+        hasInterpolation: INTERPOLATION_PATTERN.test(value),
+        tooLong: value.length > 256,
+    };
+}

package/dist/contract/schema-validate.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationError } from "../types.js";
+import type { ParsedContract } from "./load.js";
+export declare function validateContractSchema(parsed: ParsedContract, contractFile: string): ValidationError[];

package/dist/contract/schema-validate.js

@@ -0,0 +1,50 @@
+import { Ajv } from "ajv";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { contractSpan, makeError } from "../errors.js";
+import { getValuePosition } from "./load.js";
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const schemaPath = join(pkgRoot, "schema", "synology-app.schema.json");
+let compiledValidator = null;
+function getValidator() {
+    if (!compiledValidator) {
+        const ajv = new Ajv({ allErrors: true, strict: false });
+        const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+        compiledValidator = ajv.compile(schema);
+    }
+    return compiledValidator;
+}
+function mapSchemaError(error, contractFile, parsed) {
+    const path = error.instancePath.replace(/^\//, "").replace(/\//g, ".") || "schema";
+    const pos = getValuePosition(parsed.doc, path.split(".").filter(Boolean)) ?? { line: 1, column: 1 };
+    if (error.keyword === "const" && path === "schema") {
+        return makeError("CONTRACT_SCHEMA_UNSUPPORTED", contractSpan(contractFile, pos.line, pos.column, "schema"), "不支援的 App Contract schema 版本。", "請將 schema 設為整數 1。");
+    }
+    if (error.keyword === "required") {
+        const missing = String(error.params.missingProperty);
+        const missingPos = getValuePosition(parsed.doc, [missing]) ?? { line: 1, column: 1 };
+        return makeError("CONTRACT_MISSING_FIELD", contractSpan(contractFile, missingPos.line, missingPos.column, missing), `缺少必填欄位「${missing}」。`, `請在 synology-app.yaml 補上 ${missing}。`);
+    }
+    return makeError("CONTRACT_SCHEMA_INVALID", contractSpan(contractFile, pos.line, pos.column, path), `App Contract 不符合 JSON Schema：${error.message ?? error.keyword}。`, "請修正 synology-app.yaml 的欄位格式。");
+}
+export function validateContractSchema(parsed, contractFile) {
+    const validate = getValidator();
+    const data = parsed.doc.toJSON();
+    const valid = validate(data);
+    if (valid) {
+        return [];
+    }
+    const errors = validate.errors ?? [];
+    const seen = new Set();
+    const result = [];
+    for (const error of errors) {
+        const key = `${error.keyword}:${error.instancePath}:${error.params?.missingProperty ?? ""}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        result.push(mapSchemaError(error, contractFile, parsed));
+    }
+    return result;
+}

package/dist/contract/validate.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationError } from "../types.js";
+import { type ParsedContract } from "./load.js";
+export declare function validateContract(parsed: ParsedContract, contractFile: string): ValidationError[];

package/dist/contract/validate.js

@@ -0,0 +1,80 @@
+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";
+const METADATA_STRING_FIELDS = [
+    "package",
+    "version",
+    "displayname",
+    "description",
+    "maintainer",
+    "os_min_ver",
+];
+export function validateContract(parsed, contractFile) {
+    const errors = [];
+    const { contract, doc } = parsed;
+    errors.push(...validateContractSchema(parsed, contractFile));
+    for (const field of METADATA_STRING_FIELDS) {
+        const value = contract[field];
+        if (typeof value !== "string") {
+            continue;
+        }
+        errors.push(...validateDeveloperString(value, contractFile, field, getValuePosition(doc, [field]) ?? { line: 1, column: 1 }));
+    }
+    if (contract.adminport !== undefined) {
+        if (typeof contract.adminport !== "number" || !Number.isInteger(contract.adminport)) {
+            const pos = getValuePosition(doc, ["adminport"]) ?? { line: 1, column: 1 };
+            errors.push(makeError("CONTRACT_ADMINPORT_INVALID", contractSpan(contractFile, pos.line, pos.column, "adminport"), "adminport 必須是整數。", "請提供與 Compose published port 對應的數字 adminport。"));
+        }
+    }
+    errors.push(...validateInstallParameters(parsed, contractFile));
+    errors.push(...validateWebLaunch(parsed, contractFile));
+    return errors;
+}
+function validateWebLaunch(parsed, contractFile) {
+    const errors = [];
+    const { contract, doc } = parsed;
+    const web = readWebIntegration(contract);
+    if (!web || web.launch === undefined) {
+        return errors;
+    }
+    const pos = getValuePosition(doc, ["integration", "web", "launch"]) ?? { line: 1, column: 1 };
+    if (!isWebLaunchMode(web.launch)) {
+        errors.push(makeError("CONTRACT_LAUNCH_INVALID", contractSpan(contractFile, pos.line, pos.column, "integration.web.launch"), "integration.web.launch 只能是 dsm-window 或 new-page。", "請改為 dsm-window（DSM 視窗，預設）或 new-page（新分頁），Headless App 請省略此欄位。"));
+        return errors;
+    }
+    if (contract.adminport === undefined) {
+        errors.push(makeError("CONTRACT_LAUNCH_REQUIRES_WEB", contractSpan(contractFile, pos.line, pos.column, "integration.web.launch"), "Headless App 不需要 Launch Mode。", "請省略 integration.web.launch，或補上對應 Compose published port 的 adminport。"));
+    }
+    return errors;
+}
+function validateDeveloperString(value, contractFile, path, pos) {
+    const errors = [];
+    const violations = stringViolations(value);
+    if (violations.hasControlChars) {
+        errors.push(makeError("CONTRACT_INVALID_STRING", contractSpan(contractFile, pos.line, pos.column, path), "合約字串含有不允許的控制字元。", "請移除控制字元後再驗證。"));
+    }
+    if (violations.hasInterpolation) {
+        errors.push(makeError("CONTRACT_INVALID_STRING", contractSpan(contractFile, pos.line, pos.column, path), "合約字串不可包含 ${ 插值語法。", "請改為固定字面值，安裝參數請使用 install 區塊宣告。"));
+    }
+    return errors;
+}
+function validateInstallParameters(parsed, contractFile) {
+    const errors = [];
+    const { doc } = parsed;
+    for (const { name, param } of collectInstallParameters(parsed.contract)) {
+        const basePath = `install.${name}`;
+        const type = param.type;
+        if (type === "string" && typeof param.default === "string") {
+            const pos = getValuePosition(doc, ["install", name, "default"]) ?? { line: 1, column: 1 };
+            const violations = stringViolations(param.default);
+            if (violations.tooLong) {
+                errors.push(makeError("INSTALL_STRING_TOO_LONG", contractSpan(contractFile, pos.line, pos.column, `${basePath}.default`), `Install Parameter「${name}」的預設值超過 256 字元。`, "請縮短字串預設值。"));
+            }
+            if (violations.hasControlChars || violations.hasInterpolation) {
+                errors.push(makeError("INSTALL_STRING_INVALID", contractSpan(contractFile, pos.line, pos.column, `${basePath}.default`), `Install Parameter「${name}」的字串值不合法。`, "請移除控制字元與 ${ 插值語法。"));
+            }
+        }
+    }
+    return errors;
+}

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

@@ -0,0 +1,19 @@
+import type { AppContract } from "../types.js";
+/** DSM Web Station portal alias max length (error 1311 above this). */
+export declare const WEB_STATION_ALIAS_MAX = 20;
+export declare const WEB_LAUNCH_MODES: readonly ["dsm-window", "new-page"];
+export type WebLaunchMode = (typeof WEB_LAUNCH_MODES)[number];
+export declare const DEFAULT_WEB_LAUNCH_MODE: WebLaunchMode;
+export interface WebIntegration {
+    launch?: unknown;
+    cookies?: unknown;
+}
+export declare function readWebIntegration(contract: AppContract): WebIntegration | undefined;
+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 function webStationServiceName(alias: string): string;
+export declare function webStationServiceRoot(alias: string): string;
+export declare function renderWebStationResource(contract: AppContract): string;
+export declare function renderDsmWindowConfig(contract: AppContract): string;

package/dist/contract/web-launch.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+/** DSM Web Station portal alias max length (error 1311 above this). */
+export const WEB_STATION_ALIAS_MAX = 20;
+export const WEB_LAUNCH_MODES = ["dsm-window", "new-page"];
+export const DEFAULT_WEB_LAUNCH_MODE = "dsm-window";
+export function readWebIntegration(contract) {
+    const integration = contract.integration;
+    if (!integration || typeof integration !== "object") {
+        return undefined;
+    }
+    const web = integration.web;
+    if (!web || typeof web !== "object") {
+        return undefined;
+    }
+    return web;
+}
+export function isWebLaunchMode(value) {
+    return value === "dsm-window" || value === "new-page";
+}
+export function resolvedWebLaunch(contract) {
+    if (contract.adminport === undefined) {
+        return undefined;
+    }
+    const launch = readWebIntegration(contract)?.launch;
+    if (launch === undefined) {
+        return DEFAULT_WEB_LAUNCH_MODE;
+    }
+    return isWebLaunchMode(launch) ? launch : undefined;
+}
+export function webStationAlias(packageId) {
+    const slug = packageId
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (slug.length > 0 && slug.length <= WEB_STATION_ALIAS_MAX) {
+        return slug;
+    }
+    return `p${createHash("sha256").update(packageId).digest("hex").slice(0, 16)}`;
+}
+export function trustedAppEntryPath(contract) {
+    const alias = webStationAlias(String(contract.package ?? ""));
+    const adminurl = String(contract.adminurl ?? "/").trim() || "/";
+    const extra = adminurl.startsWith("/") ? adminurl : `/${adminurl}`;
+    if (extra === "/") {
+        return `/${alias}/`;
+    }
+    return `/${alias}${extra}`;
+}
+export function webStationServiceName(alias) {
+    return `PROXY-${alias}`;
+}
+export function webStationServiceRoot(alias) {
+    return `web/synopkgland-${alias}`;
+}
+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),
+        type: "static",
+        support_alias: true,
+        support_server: false,
+        root: webStationServiceRoot(alias),
+    };
+    const portal = {
+        service: webStationServiceName(alias),
+        name: alias,
+        type: "alias",
+        alias,
+    };
+    if (launch === "dsm-window") {
+        portal.app = String(contract.package);
+    }
+    return `${JSON.stringify({ webservice: { services: [service], portals: [portal] } }, null, 2)}\n`;
+}
+export function renderDsmWindowConfig(contract) {
+    const packageId = String(contract.package);
+    return `${JSON.stringify({
+        ".url": {
+            [packageId]: {
+                type: "url",
+                allUsers: true,
+                title: String(contract.displayname ?? packageId),
+                desc: String(contract.description ?? ""),
+                icon: "images/app_{0}.png",
+                url: trustedAppEntryPath(contract),
+            },
+        },
+    }, null, 2)}\n`;
+}

package/dist/deploy/catalog-publish.d.ts

@@ -0,0 +1,3 @@
+import { type PublishSpkResult } from "@synopackageland/package-source/publish-spk";
+export declare function publishBuiltSpk(spkPath: string): Promise<PublishSpkResult>;
+export declare function packageSourceOrigin(): string;

package/dist/deploy/catalog-publish.js

@@ -0,0 +1,7 @@
+import { publishSpkToSource, resolvePublishTarget, } from "@synopackageland/package-source/publish-spk";
+export async function publishBuiltSpk(spkPath) {
+    return publishSpkToSource(spkPath, resolvePublishTarget());
+}
+export function packageSourceOrigin() {
+    return resolvePublishTarget().origin;
+}

package/dist/deploy/deploy.d.ts

@@ -0,0 +1,22 @@
+import type { ProjectRoot } from "../discovery.js";
+import type { NasHost } from "../host/types.js";
+import type { PublishSpkResult } from "@synopackageland/package-source/publish-spk";
+export interface DeployProjectOptions {
+    project: ProjectRoot;
+    host: NasHost;
+    dev?: boolean;
+    replaceCurated?: boolean;
+    catalogPublish?: (spkPath: string) => Promise<PublishSpkResult>;
+    shareValues?: Record<string, string>;
+    runAsValues?: Record<string, string>;
+}
+export interface DeployProjectResult {
+    ok: boolean;
+    code?: string;
+    message?: string;
+    packageId?: string;
+    spkPath?: string;
+    openUrl?: string;
+    catalogVersion?: string;
+}
+export declare function deployProject(options: DeployProjectOptions): Promise<DeployProjectResult>;

package/dist/deploy/deploy.js

@@ -0,0 +1,136 @@
+import { buildSpk } from "../build-spk/generator.js";
+import { loadContract } from "../contract/load.js";
+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 { resolveDeploySpkVersion } from "./spk-version.js";
+import { resolveSharedFolderExtraValues, sharedFolderParameterNames } from "./share-values.js";
+import { resolveDsmUserExtraValues, dsmUserParameterNames } from "./run-as-values.js";
+const CURATED_DEPLOY_REFUSED_MESSAGE = "此 NAS 已持有 Curated App Package Attestation。請改用 --dev，或使用 --replace-curated 明確降級。";
+function brokerCapabilitiesFromContract(project) {
+    const contract = loadContract(project.contractPath).contract;
+    const capabilities = ["identity"];
+    const integration = contract.integration;
+    if (integration?.files) {
+        capabilities.push("files");
+    }
+    return capabilities;
+}
+export async function deployProject(options) {
+    const validation = validateProject(options.project);
+    if (!validation.ok) {
+        return { ok: false, code: "VALIDATION_FAILED", message: validation.errors.map((e) => e.code).join(", ") };
+    }
+    const identity = resolveDeployIdentity(options.project, { dev: options.dev });
+    const contract = loadContract(options.project.contractPath).contract;
+    const shareResolved = await resolveSharedFolderExtraValues({
+        requiredKeys: sharedFolderParameterNames(contract),
+        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),
+        provided: options.runAsValues ?? {},
+        existingEnv: (await options.host.getInstalledProjectEnv?.(identity.packageId)) ?? {},
+    });
+    if (!runAsResolved.ok) {
+        return { ok: false, code: runAsResolved.code, message: runAsResolved.message };
+    }
+    const extraValues = { ...shareResolved.extraValues, ...runAsResolved.extraValues };
+    const contractDigest = digestProjectContract(options.project);
+    const bundleDigest = digestProjectBundle(options.project);
+    try {
+        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 spkVersion = await resolveDeploySpkVersion(options.project, options.host, identity.packageId);
+    const build = await buildSpk({
+        project: options.project,
+        packageIdentity: identity.packageId,
+        displayname: identity.displayname,
+        spkVersion,
+    });
+    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,
+            });
+        }
+    }
+    catch (error) {
+        return {
+            ok: false,
+            code: "CATALOG_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,
+    };
+}

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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,14 @@
+const DEV_SUFFIX = ".dev";
+const DEV_DISPLAY_SUFFIX = "（開發中）";
+export function developmentPackageIdentity(packageIdentity) {
+    return `${packageIdentity}${DEV_SUFFIX}`;
+}
+export function isDevelopmentPackageIdentity(packageIdentity) {
+    return packageIdentity.endsWith(DEV_SUFFIX) && packageIdentity.length > DEV_SUFFIX.length;
+}
+export function developmentDisplayName(displayname) {
+    if (displayname.includes(DEV_DISPLAY_SUFFIX)) {
+        return displayname;
+    }
+    return `${displayname}${DEV_DISPLAY_SUFFIX}`;
+}

package/dist/deploy/identity.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectRoot } from "../discovery.js";
+import type { DeployIdentity } from "../host/types.js";
+export { developmentDisplayName, developmentPackageIdentity, isDevelopmentPackageIdentity, } from "./identity-shared.js";
+export interface ResolveDeployIdentityOptions {
+    dev?: boolean;
+}
+export declare function resolveDeployIdentity(project: ProjectRoot, options: ResolveDeployIdentityOptions): DeployIdentity;

package/dist/deploy/identity.js

@@ -0,0 +1,20 @@
+import { developmentDisplayName, developmentPackageIdentity, } from "./identity-shared.js";
+import { loadContract } from "../contract/load.js";
+export { developmentDisplayName, developmentPackageIdentity, isDevelopmentPackageIdentity, } from "./identity-shared.js";
+export function resolveDeployIdentity(project, options) {
+    const parsed = loadContract(project.contractPath);
+    const basePackage = String(parsed.contract.package ?? "");
+    const baseDisplay = String(parsed.contract.displayname ?? basePackage);
+    if (options.dev) {
+        return {
+            packageId: developmentPackageIdentity(basePackage),
+            displayname: developmentDisplayName(baseDisplay),
+            developmentInstance: true,
+        };
+    }
+    return {
+        packageId: basePackage,
+        displayname: baseDisplay,
+        developmentInstance: false,
+    };
+}

package/dist/deploy/package-source.d.ts

@@ -0,0 +1,7 @@
+import { DEFAULT_PACKAGE_SOURCE_ORIGIN, fetchPackageSourceManifest, publishSpkToSource, resolvePublishTarget, type PublishTarget, type PublishSpkResult } from "@synology/package-source/publish-spk";
+import { resolveNextSpkVersion } from "@synology/package-source/next-version";
+import type { IndexManifest } from "@synology/package-source/index-manifest";
+export { DEFAULT_PACKAGE_SOURCE_ORIGIN, fetchPackageSourceManifest, publishSpkToSource, resolvePublishTarget, resolveNextSpkVersion, };
+export type { PublishTarget, PublishSpkResult, IndexManifest };
+export declare function resolvePackageSourceManifest(origin?: string): Promise<IndexManifest | null>;
+export declare function publishBuiltSpk(spkPath: string, target?: PublishTarget): Promise<PublishSpkResult>;

package/dist/deploy/package-source.js

@@ -0,0 +1,17 @@
+import { DEFAULT_PACKAGE_SOURCE_ORIGIN, fetchPackageSourceManifest, publishSpkToSource, resolvePublishTarget, } from "@synology/package-source/publish-spk";
+import { resolveNextSpkVersion } from "@synology/package-source/next-version";
+export { DEFAULT_PACKAGE_SOURCE_ORIGIN, fetchPackageSourceManifest, publishSpkToSource, resolvePublishTarget, resolveNextSpkVersion, };
+const LIVE_TEST_FALLBACK_ORIGIN = "https://syno-package-source-throwaway.bidacumen.workers.dev";
+export async function resolvePackageSourceManifest(origin = resolvePublishTarget().origin) {
+    const manifest = await fetchPackageSourceManifest(origin);
+    if (manifest) {
+        return manifest;
+    }
+    if (origin !== LIVE_TEST_FALLBACK_ORIGIN) {
+        return fetchPackageSourceManifest(LIVE_TEST_FALLBACK_ORIGIN);
+    }
+    return null;
+}
+export async function publishBuiltSpk(spkPath, target = resolvePublishTarget()) {
+    return publishSpkToSource(spkPath, target);
+}

package/dist/deploy/run-as-values.d.ts

@@ -0,0 +1,18 @@
+import type { AppContract } from "../types.js";
+export declare const DSM_USER_REQUIRED = "DSM_USER_REQUIRED";
+export declare const DSM_USER_LOGICAL_NAME_REQUIRED = "DSM_USER_LOGICAL_NAME_REQUIRED";
+export declare function dsmUserParameterNames(contract: AppContract): string[];
+export declare function isNumericUidInput(value: string): boolean;
+export type RunAsResolveResult = {
+    ok: true;
+    extraValues: Record<string, string>;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+export declare function resolveDsmUserExtraValues(input: {
+    requiredKeys: string[];
+    provided: Record<string, string>;
+    existingEnv?: Record<string, string>;
+}): RunAsResolveResult;

package/dist/deploy/run-as-values.js

@@ -0,0 +1,48 @@
+import { collectInstallParameters } from "../contract/load.js";
+export const DSM_USER_REQUIRED = "DSM_USER_REQUIRED";
+export const DSM_USER_LOGICAL_NAME_REQUIRED = "DSM_USER_LOGICAL_NAME_REQUIRED";
+export function dsmUserParameterNames(contract) {
+    return collectInstallParameters(contract)
+        .filter((item) => item.param.type === "dsm_user")
+        .map((item) => item.name);
+}
+export function isNumericUidInput(value) {
+    return /^(0|[1-9][0-9]*)(:(0|[1-9][0-9]*))?$/.test(value.trim());
+}
+export function resolveDsmUserExtraValues(input) {
+    if (input.requiredKeys.length === 0) {
+        return { ok: true, extraValues: {} };
+    }
+    const extraValues = {};
+    const missing = [];
+    for (const key of input.requiredKeys) {
+        const raw = input.provided[key];
+        if (raw === undefined || raw.trim() === "") {
+            const existing = input.existingEnv?.[key];
+            if (typeof existing === "string" && existing.trim() !== "" && !isNumericUidInput(existing)) {
+                extraValues[key] = existing.trim();
+                continue;
+            }
+            missing.push(key);
+            continue;
+        }
+        const logical = raw.trim();
+        if (isNumericUidInput(logical) || logical === "root") {
+            return {
+                ok: false,
+                code: DSM_USER_LOGICAL_NAME_REQUIRED,
+                message: `Container Run-as「${key}」必須是這台 NAS 上的 DSM 使用者邏輯名，不能傳數字 uid。`,
+            };
+        }
+        extraValues[key] = logical;
+    }
+    if (missing.length > 0) {
+        const example = `--run-as ${missing[0]}=alice`;
+        return {
+            ok: false,
+            code: DSM_USER_REQUIRED,
+            message: `契約有 Container Run-as「${missing.join("、")}」。請傳這台 NAS 上的 DSM 使用者邏輯名（例如 ${example}）。禁止把數字 uid 寫進 extra_values。`,
+        };
+    }
+    return { ok: true, extraValues };
+}