@synopackageland/cli 0.6.1 → 0.7.1

package/dist/host/dsm-http.js

@@ -2,11 +2,29 @@ import { spawnSync } from "node:child_process";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-function isHostUnreachable(error) {
-    const code = error.cause?.code
+function errorCode(error) {
+    return error.cause?.code
         ?? error.code;
+}
+function isHostUnreachable(error) {
+    const code = errorCode(error);
     return code === "EHOSTUNREACH" || code === "ENETUNREACH";
 }
+const UNTRUSTED_CERTIFICATE = new Set([
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "CERT_HAS_EXPIRED",
+    "ERR_TLS_CERT_ALTNAME_INVALID",
+]);
+/** Node reports an untrusted certificate only as "fetch failed"; say what to do. Verification stays on. */
+function untrustedCertificate(url, code) {
+    const origin = new URL(url).origin;
+    return Object.assign(new Error(`DSM at ${origin} presented a TLS certificate this computer does not trust (${code}). ` +
+        `Export the NAS certificate or its CA as PEM and run with NODE_EXTRA_CA_CERTS=<that file>, ` +
+        `or give DSM a certificate whose name matches the host profile. Certificate checks stay on.`), { code: "DSM_TLS_UNTRUSTED" });
+}
 function headerRecord(headers) {
     if (!headers) {
         return {};
@@ -24,6 +42,10 @@ export async function dsmFetch(url, init = {}) {
         return await fetch(url, init);
     }
     catch (error) {
+        const code = errorCode(error);
+        if (code && UNTRUSTED_CERTIFICATE.has(code)) {
+            throw untrustedCertificate(url, code);
+        }
         if (!isHostUnreachable(error)) {
             throw error;
         }

package/dist/host/types.d.ts

@@ -2,6 +2,7 @@ import type { SharePermissionListing } from "../deploy/share-permission-prefligh
 import type { InstalledPackageState } from "./catalog-install.js";
 import type { PortInfoEntry } from "./port-info.js";
 import type { DsmPortProfileInventory } from "./dsm-port-profile.js";
+import type { NativeArchFamily } from "../build-spk/dsm-arch.js";
 export interface DeployIdentity {
     packageId: string;
     displayname: string;
@@ -32,8 +33,9 @@ export interface NasHost {
         ready: boolean;
         executor_digest: string;
         policy_digest: string;
+        error?: string;
     } | undefined>;
-    getArchFamily?(): Promise<"x86_64" | "aarch64" | undefined>;
+    getArchFamily?(): Promise<NativeArchFamily | undefined>;
     /** List the current logical Shared Folder names using an administrator session. */
     listShareNames?(): Promise<string[]>;
     resolveSharePath?(logicalName: string): Promise<string | undefined>;

package/dist/info.js

@@ -5,7 +5,9 @@ import { appOriginFromContract } from "./host/open-url.js";
 import { resolveDeployIdentity } from "./deploy/identity.js";
 import { loadStandaloneManifest, } from "./standalone/manifest.js";
 import { inspectSpk } from "./standalone/inspect-spk.js";
-import { executorPolicy } from "./runtime/executor-policy.js";
+import { isNativeLayout, loadNativeLayout } from "./standalone/native-layout.js";
+import { executorPolicy, executorPolicyText, sha256 } from "./runtime/executor-policy.js";
+import { executorTasks } from "./runtime/executor-tasks.js";
 import { uninstallCleanup } from "./runtime/uninstall-cleanup.js";
 export async function projectInfo(options) {
     const identity = resolveDeployIdentity(options.project, { dev: options.dev });
@@ -63,6 +65,21 @@ export function classifyRootTasks(expected, inventory) {
         ? result("needs-admin-approval", "Approve missing or outdated root tasks in the DSM package UI.")
         : result("ready", "Boot and control tasks match the executor and policy digests. Executor health must be checked in the App window.");
 }
+async function liveRootCapability(m, host) {
+    try {
+        const policyDigest = sha256(executorPolicyText(executorPolicy(m)));
+        const classified = classifyRootTasks(executorTasks({ package: m.package, policyDigest }), await host.getRootTaskInventory?.(m.package));
+        if (classified.state !== "ready")
+            return classified;
+        const observed = await host.getExecutorStatus?.(m.package);
+        if (observed?.ready !== true || observed.policy_digest !== policyDigest)
+            return { ...classified, state: "blocked", reason: observed?.error ?? "Executor health or policy digest readback could not be verified." };
+        return { ...classified, reason: "Root tasks and the running executor match the source policy (no local SPK, so executor bytes were not compared)." };
+    }
+    catch {
+        return { name: "rootOps", state: "blocked", reason: "DSM executor or root task readback could not be verified." };
+    }
+}
 async function rootCapability(m, host, version) {
     const blocked = (reason) => ({
         name: "rootOps",
@@ -82,7 +99,7 @@ async function rootCapability(m, host, version) {
         return blocked("NAS architecture cannot be matched to the local executor SPK artifact.");
     const spk = join(m.root, "dist", `${m.package}-${version}-${arch}.spk`);
     if (!existsSync(spk))
-        return blocked("Built executor SPK artifact is unavailable; build this installed version first.");
+        return liveRootCapability(m, host);
     try {
         const inspected = await inspectSpk(spk);
         if (inspected.findings.length ||
@@ -100,7 +117,7 @@ async function rootCapability(m, host, version) {
         if (classified.state === "ready") {
             const observed = await host.getExecutorStatus?.(m.package);
             if (!observed || observed.ready !== true || observed.executor_digest !== executor.executorDigest || observed.policy_digest !== executor.policyDigest)
-                return { ...classified, executor, state: "blocked", reason: "Executor health or digest readback could not be verified." };
+                return { ...classified, executor, state: "blocked", reason: observed?.error ?? "Executor health or digest readback could not be verified." };
         }
         return { ...classified, executor };
     }
@@ -111,12 +128,14 @@ async function rootCapability(m, host, version) {
 export async function standaloneInfo(options) {
     if (options.dev)
         throw Object.assign(new Error("--dev is not supported for native-go/binary; choose a distinct package name at init"), { code: "DEVELOPMENT_INSTANCE_UNSUPPORTED" });
+    if (isNativeLayout(options.root))
+        return nativeLayoutInfo(options.root, options.host);
     const loaded = loadStandaloneManifest(options.root);
     if (!loaded.ok)
         throw Object.assign(new Error(loaded.errors.map((e) => e.message).join("\n")), { code: loaded.errors[0].code });
     const m = loaded.manifest;
-    const remote = await options.host.getInstalledPackageState?.(m.package);
-    const installed = await options.host.isPackageInstalled(m.package);
+    const { remote, ...state } = await packageState(m.package, options.host);
+    const installed = state.installed;
     const capabilities = [];
     let executor;
     for (const name of ["files", "jobs", "identity", "rootOps", "delegate"]) {
@@ -142,16 +161,32 @@ export async function standaloneInfo(options) {
             });
     }
     return {
-        packageIdentity: m.package,
-        developmentInstance: false,
-        installed,
-        readiness: remote?.status ?? (installed ? "UNKNOWN" : "NOT_INSTALLED"),
-        openUrl: `${options.host.dsmOrigin.replace(/\/$/, "")}/?launchApp=SYNO.SDS.${m.package}.Instance`,
+        ...state,
         capabilities,
         ...(executor ? { executor } : {}),
         uninstallCleanup: uninstallCleanup(m.package, Boolean(m.capabilities.rootOps || m.capabilities.delegate)),
     };
 }
+/** A native layout has no SDK capabilities; report package state only. */
+async function nativeLayoutInfo(root, host) {
+    const loaded = loadNativeLayout(root);
+    if (!loaded.ok)
+        throw Object.assign(new Error(loaded.errors.map((e) => e.message).join("\n")), { code: loaded.errors[0].code });
+    const { remote, ...state } = await packageState(loaded.manifest.package, host);
+    return { ...state, capabilities: [] };
+}
+async function packageState(pkg, host) {
+    const remote = await host.getInstalledPackageState?.(pkg);
+    const installed = await host.isPackageInstalled(pkg);
+    return {
+        remote,
+        packageIdentity: pkg,
+        developmentInstance: false,
+        installed,
+        readiness: remote?.status ?? (installed ? "UNKNOWN" : "NOT_INSTALLED"),
+        openUrl: `${host.dsmOrigin.replace(/\/$/, "")}/?launchApp=SYNO.SDS.${pkg}.Instance`,
+    };
+}
 export function formatProjectInfo(info) {
     return [
         `Package Identity：${info.packageIdentity}`,

package/dist/init.d.ts

@@ -1,8 +1,11 @@
+import { type CapabilityName } from "./capabilities.js";
 import type { TemplateName } from "./types.js";
 /** The container templates need DSM 7.2.1 or later; native-go and binary need 7.1. */
 export declare function isContainerTemplate(template: TemplateName): boolean;
 export declare function isTemplateName(value: string): value is TemplateName;
 export declare function listTemplates(): TemplateName[];
+/** New native scaffolds opt in explicitly; existing manifests are never migrated. */
+export declare function nativeCapabilitySettings(names: readonly CapabilityName[]): Record<string, unknown>;
 export interface InitOptions {
     /** os_min_ver of the new project: a release (7.2) or a full 7.x-build; default is the template's (DSM 7.1 for native-go/binary, DSM 7.2.1 for container templates). */
     minDsm?: string;

package/dist/init.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
-import { parse, stringify } from "yaml";
+import { isMap, isScalar, parse, parseDocument, stringify } from "yaml";
 import { capabilityNames, capabilitySettings } from "./capabilities.js";
+import { MOVE_FROM_STAGING } from './runtime/delegate-contract.js';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, join, relative } from "node:path";
 import { templatesRoot } from "./template-paths.js";
@@ -25,6 +26,15 @@ export function isTemplateName(value) {
 export function listTemplates() {
     return [...TEMPLATE_NAMES];
 }
+/** New native scaffolds opt in explicitly; existing manifests are never migrated. */
+export function nativeCapabilitySettings(names) {
+    const settings = capabilitySettings(names);
+    if (names.includes('delegate'))
+        settings.delegate = {
+            scope: 'install-selected', operations: [MOVE_FROM_STAGING], destinations: ['save'], lifetime: 'until-revoked',
+        };
+    return settings;
+}
 /**
  * native-go --with root-ops: files laid over the native-go template, and the
  * files they replace.
@@ -85,10 +95,12 @@ function isTemplateBuildArtifact(path) {
 }
 export function initFromTemplate(template, targetDir, options = {}) {
     if (!isTemplateName(template))
-        throw new Error(`[INIT_TEMPLATE_INVALID] 未知模板：${template}`);
+        throw new Error(`[INIT_TEMPLATE_UNKNOWN] 未知模板：${template}`);
     const caps = capabilityNames(options.with ?? []);
     if (caps.includes("login") && resolvedUi(template, options) === "plain")
         throw new Error("[CAPABILITY_COMBINATION_INVALID] login 需要獨立登入頁；plain UI 不支援，請改用 --ui vue。");
+    if (caps.includes("delegate") && resolvedUi(template, options) === "plain")
+        throw new Error("[CAPABILITY_COMBINATION_INVALID] delegate 的 install-selected scope 只能在 Vue 面板確認；plain UI 不支援，請改用 --ui vue。");
     if (options.from && template !== "compose")
         throw new Error("[INIT_OPTIONS_UNSUPPORTED] --from 只適用於 compose。");
     if (caps.length && template !== "native-go")
@@ -183,7 +195,7 @@ export function initFromTemplate(template, targetDir, options = {}) {
     }
     if (executor) {
         const path = join(targetDir, "backend/internal/app/routes_test.go");
-        writeFileSync(path, readFileSync(path, "utf8").replace('if strings.HasPrefix(r.Method(), "jobs.") {', 'if r.Method() == "executor.status" { want = "internal" }\n\t\tif r.Method() == "root.run" { want = "session_required" }\n\t\tif strings.HasPrefix(r.Method(), "jobs.") {'));
+        writeFileSync(path, readFileSync(path, "utf8").replace('if strings.HasPrefix(r.Method(), "jobs.") {', 'if r.Method() == "root.run" { want = "session_required" }\n\t\tif strings.HasPrefix(r.Method(), "jobs.") {'));
     }
     if (background && ui === "vue") {
         const app = join(targetDir, "frontend/src/App.vue");
@@ -194,20 +206,11 @@ export function initFromTemplate(template, targetDir, options = {}) {
     if (template !== "compose") {
         const path = join(targetDir, "dsm-package.yaml");
         const raw = parse(readFileSync(path, "utf8"));
-        raw.capabilities = capabilitySettings(caps);
-        writeFileSync(path, stringify(raw));
-    }
-    if (template === "compose" && options.from) {
-        const imported = readFileSync(options.from, "utf8");
-        const compose = parse(imported);
-        if (!compose || typeof compose !== "object" || !compose.services)
-            throw new Error("[INIT_COMPOSE_INVALID] --from 需要包含 services 的 Compose YAML。");
-        writeFileSync(join(targetDir, "compose.yaml"), imported);
-        const path = join(targetDir, "synology-app.yaml");
-        const raw = parse(readFileSync(path, "utf8"));
-        delete raw.install;
+        raw.capabilities = nativeCapabilitySettings(caps);
         writeFileSync(path, stringify(raw));
     }
+    if (template === "compose" && options.from)
+        importCompose(options.from, targetDir, options);
     if (template === "binary") {
         mkdirSync(join(targetDir, "prebuilt"), { recursive: true });
         for (const [arch, goarch] of [["x86_64", "amd64"], ["aarch64", "arm64"]]) {
@@ -221,6 +224,35 @@ export function initFromTemplate(template, targetDir, options = {}) {
         writeFileSync(manifest, readFileSync(manifest, "utf8") + sharedFolderYaml(options.sharedFolder));
     }
 }
+/**
+ * --from replaces the example Compose. The manifest takes the requested (or
+ * directory-derived) identity and keeps only the example install entries the
+ * imported Compose references as `${KEY}` (or `${KEY_UID}`／`${KEY_GID}`).
+ */
+function importCompose(from, targetDir, options) {
+    const imported = readFileSync(from, "utf8");
+    const compose = parse(imported);
+    if (!compose || typeof compose !== "object" || !compose.services)
+        throw new Error("[INIT_COMPOSE_INVALID] --from 需要包含 services 的 Compose YAML。");
+    writeFileSync(join(targetDir, "compose.yaml"), imported);
+    const path = join(targetDir, "synology-app.yaml");
+    const doc = parseDocument(readFileSync(path, "utf8"));
+    doc.set("package", options.packageId ?? defaultPackageId(targetDir));
+    doc.set("displayname", validDisplayName(options.displayName ?? defaultDisplayName(targetDir)));
+    const install = doc.get("install");
+    const referenced = new Set([...imported.matchAll(/\$\{([A-Z][A-Z0-9_]*?)(?:_UID|_GID)?\}/g)].map(match => match[1]));
+    if (isMap(install))
+        install.items = install.items.filter(item => referenced.has(String(isScalar(item.key) ? item.key.value : item.key)));
+    if (!isMap(install) || install.items.length === 0)
+        doc.delete("install");
+    writeFileSync(path, String(doc));
+}
+function validDisplayName(displayName) {
+    if (displayName.trim() === "" || /[\r\n"\\]/.test(displayName)) {
+        throw new Error("[INIT_DISPLAY_NAME_INVALID] 顯示名稱必須是單行，且不含 \" 或 \\。");
+    }
+    return displayName;
+}
 /** The `install.sharedFolder` block, validated by the same reader build-spk uses. */
 function sharedFolderYaml(options) {
     const folder = { mode: options.mode, key: options.key ?? "shared", ...(options.name === undefined ? {} : { name: options.name }), permission: options.permission ?? "rw" };
@@ -243,15 +275,14 @@ function substitutionsFor(template, targetDir, options) {
     if (options.ui !== undefined && !["plain", "vue"].includes(options.ui))
         throw new Error("[INIT_UI_INVALID] --ui 只接受 plain 或 vue。");
     if (!SUBSTITUTED[template]) {
+        if (options.from && options.displayName !== undefined)
+            validDisplayName(options.displayName);
         return {};
     }
     const packageId = options.packageId ?? defaultPackageId(targetDir);
     if (!PACKAGE_ID.test(packageId)) {
         throw new Error(`[INIT_PACKAGE_INVALID] package「${packageId}」必須以英文字母開頭，只含英數字（2–64 字），例如 PhotoTagger。`);
     }
-    const displayName = options.displayName ?? defaultDisplayName(targetDir);
-    if (displayName.trim() === "" || /[\r\n"\\]/.test(displayName)) {
-        throw new Error("[INIT_DISPLAY_NAME_INVALID] 顯示名稱必須是單行，且不含 \" 或 \\。");
-    }
+    const displayName = validDisplayName(options.displayName ?? defaultDisplayName(targetDir));
     return { __PACKAGE__: packageId, __DISPLAY_NAME__: displayName, __BACKGROUND_ENABLED__: caps.includes("jobs") || caps.includes("delegate") ? "true" : "false" };
 }

package/dist/package-metadata.d.ts

@@ -0,0 +1,21 @@
+/** Plain text, or a map from a BCP-47 tag (en, zh-TW, ...) to plain text. */
+export type LocalizedText = string | Record<string, string>;
+export interface PackageMetadata {
+    long_description?: LocalizedText;
+    changelog?: LocalizedText;
+    contact_email?: string;
+    support_email?: string;
+    homepage?: string;
+    source_url?: string;
+    issues_url?: string;
+    license?: string;
+    maintainer_url?: string;
+    distributor?: string;
+    distributor_url?: string;
+    support_url?: string;
+    helpurl?: string;
+    screenshots?: string[];
+}
+export declare function safeMetadataUrl(value: unknown, mail?: boolean): value is string;
+export declare function validateMetadata(raw: unknown): PackageMetadata;
+export declare function metadataInfoFields(metadata?: PackageMetadata): [string, string][];

package/dist/package-metadata.js

@@ -0,0 +1,101 @@
+export function safeMetadataUrl(value, mail = false) {
+    if (typeof value !== "string" || value.length > 2048)
+        return false;
+    try {
+        const u = new URL(value);
+        return (!u.username &&
+            !u.password &&
+            (["https:", "http:"].includes(u.protocol) ||
+                (mail &&
+                    u.protocol === "mailto:" &&
+                    /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(u.pathname))));
+    }
+    catch {
+        return false;
+    }
+}
+export function validateMetadata(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("invalid metadata");
+    const allowed = [
+        "long_description",
+        "changelog",
+        "contact_email",
+        "support_email",
+        "homepage",
+        "source_url",
+        "issues_url",
+        "license",
+        "maintainer_url",
+        "distributor",
+        "distributor_url",
+        "support_url",
+        "helpurl",
+        "screenshots",
+    ];
+    for (const [k, v] of Object.entries(raw)) {
+        if (!allowed.includes(k))
+            throw new Error("unknown metadata");
+        if (k === "screenshots") {
+            if (!Array.isArray(v) ||
+                v.length > 12 ||
+                !v.every((u) => safeMetadataUrl(u)))
+                throw new Error("invalid screenshots");
+        }
+        else if ((k === "long_description" || k === "changelog") &&
+            typeof v === "object" &&
+            v &&
+            !Array.isArray(v)) {
+            if (Object.entries(v).length > 32 ||
+                !Object.entries(v).every(([lang, t]) => /^[a-z]{2}(?:-[A-Za-z]{2})?$/.test(lang) &&
+                    typeof t === "string" &&
+                    t.length <= 16000 &&
+                    !/[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(t)))
+                throw new Error("invalid localized description");
+        }
+        else if (typeof v !== "string" ||
+            v.length > 16000 ||
+            /[\x00-\x08\x0b\x0c\x0e-\x1f]/.test(v))
+            throw new Error("invalid text");
+        if (k.endsWith("_email") &&
+            (typeof v !== "string" || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v)))
+            throw new Error("invalid email");
+        if ([
+            "homepage",
+            "source_url",
+            "issues_url",
+            "maintainer_url",
+            "distributor_url",
+            "support_url",
+            "helpurl",
+        ].includes(k) &&
+            !safeMetadataUrl(v, k === "support_url"))
+            throw new Error("invalid metadata URL");
+    }
+    if (JSON.stringify(raw).length > 32000)
+        throw new Error("metadata too large");
+    return raw;
+}
+export function metadataInfoFields(metadata) {
+    if (!metadata)
+        return [];
+    const m = validateMetadata(metadata), fields = [];
+    // INFO has one changelog; a per-language map contributes its English text.
+    const changelog = typeof m.changelog === "object"
+        ? (m.changelog.en ?? Object.values(m.changelog)[0])
+        : m.changelog;
+    for (const [k, v] of [
+        ["maintainer_url", m.maintainer_url],
+        ["distributor", m.distributor],
+        ["distributor_url", m.distributor_url],
+        ["support_url", m.support_url],
+        ["helpurl", m.helpurl],
+        ["changelog", changelog],
+    ])
+        if (v)
+            fields.push([k, v.replace(/\r?\n/g, " · ")]);
+    if (!m.support_url && m.support_email)
+        fields.push(["support_url", "mailto:" + m.support_email]);
+    fields.push(["spk_land_metadata", JSON.stringify(m)]);
+    return fields;
+}

package/dist/portal/alias.d.ts

@@ -0,0 +1,25 @@
+import type { AppContract } from "../types.js";
+/**
+ * DSM Application Portal alias: `https://<nas>/<alias>/` opens the App after
+ * DSM sign-in. DSM itself only refuses empty aliases (4100), synoman
+ * directory names (4102) and aliases another App uses (4103); the SDK keeps a
+ * stricter, URL-safe rule so the same value works in links and shell scripts.
+ */
+export declare const PORTAL_ALIAS_PATTERN: RegExp;
+export declare const PORTAL_ALIAS_MAX = 64;
+/**
+ * Names DSM already serves: /usr/syno/synoman entries and the default aliases
+ * of Synology Apps, as observed on DSM 7.4-90069. DSM stays the authority.
+ */
+export declare const RESERVED_PORTAL_ALIASES: readonly string[];
+export interface PortalDeclaration {
+    alias: string;
+}
+export declare function isPortalAlias(value: unknown): value is string;
+/** The package name as a slug; a reserved or too long name falls back to a stable hash. */
+export declare function defaultPortalAlias(packageId: string): string;
+/** `{}` or `{alias}`; undefined for any other shape. */
+export declare function readPortalDeclaration(value: unknown, packageId: string): PortalDeclaration | undefined;
+/** A Compose App reaches the portal only as a DSM window behind the DSM-authenticated gateway. */
+export declare function contractPortalSupported(contract: AppContract): boolean;
+export declare function resolvedContractPortal(contract: AppContract): PortalDeclaration | undefined;

package/dist/portal/alias.js

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+import { readWebIntegration, resolvedWebLaunch, usesAuthGateway } from "../contract/web-launch.js";
+/**
+ * DSM Application Portal alias: `https://<nas>/<alias>/` opens the App after
+ * DSM sign-in. DSM itself only refuses empty aliases (4100), synoman
+ * directory names (4102) and aliases another App uses (4103); the SDK keeps a
+ * stricter, URL-safe rule so the same value works in links and shell scripts.
+ */
+export const PORTAL_ALIAS_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+export const PORTAL_ALIAS_MAX = 64;
+/**
+ * Names DSM already serves: /usr/syno/synoman entries and the default aliases
+ * of Synology Apps, as observed on DSM 7.4-90069. DSM stays the authority.
+ */
+export const RESERVED_PORTAL_ALIASES = [
+    "dsfile", "indexdb", "mobile", "oauth", "scripts", "sharing", "ssdp", "synosdsjslib", "synohdpack", "webapi", "webman",
+    "calendar", "chatplus", "contacts", "drive", "file", "photo", "sso", "synologymeet",
+];
+export function isPortalAlias(value) {
+    return typeof value === "string" && PORTAL_ALIAS_PATTERN.test(value) && !RESERVED_PORTAL_ALIASES.includes(value);
+}
+/** The package name as a slug; a reserved or too long name falls back to a stable hash. */
+export function defaultPortalAlias(packageId) {
+    const slug = packageId.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return isPortalAlias(slug) ? slug : `app-${createHash("sha256").update(packageId).digest("hex").slice(0, 12)}`;
+}
+/** `{}` or `{alias}`; undefined for any other shape. */
+export function readPortalDeclaration(value, packageId) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const keys = Object.keys(value);
+    if (keys.some((key) => key !== "alias"))
+        return undefined;
+    const alias = value.alias;
+    if (alias === undefined)
+        return { alias: defaultPortalAlias(packageId) };
+    return isPortalAlias(alias) ? { alias } : undefined;
+}
+/** A Compose App reaches the portal only as a DSM window behind the DSM-authenticated gateway. */
+export function contractPortalSupported(contract) {
+    return resolvedWebLaunch(contract) === "dsm-window" && usesAuthGateway(contract);
+}
+export function resolvedContractPortal(contract) {
+    const portal = readWebIntegration(contract)?.portal;
+    if (portal === undefined || !contractPortalSupported(contract))
+        return undefined;
+    return readPortalDeclaration(portal, String(contract.package ?? ""));
+}

package/dist/portal/package.d.ts

@@ -0,0 +1,33 @@
+import type { Translate } from "../build-spk/wizard-i18n.js";
+import type { InstallWizardStep } from "../build-spk/install-wizard.js";
+import type { AppContract } from "../types.js";
+/** Package payload paths DSM's app-portal worker copies to /usr/syno/etc/www/app.d at start. */
+export declare const PORTAL_JSON_RELPATH = "etc/portal.json";
+export declare const PORTAL_MUSTACHE_RELPATH = "etc/portal.mustache";
+/** Install wizard key; DSM exports it to preinst/postinst. */
+export declare const PORTAL_INSTALL_KEY = "portal_alias";
+/** Package-owned install draft, never DSM's saved portal configuration. */
+export declare const PORTAL_DRAFT = "portal-install.json";
+export interface PortalPackage {
+    /** The DSM app id the alias opens: an AppInstance or a `.url` entry of ui/config. */
+    appId: string;
+    /** Control Panel display name. */
+    application: string;
+    /** Default alias; the wizard answer replaces it. */
+    alias: string;
+}
+/** A Compose portal opens the App's `.url` entry of ui/config, keyed by the package id. */
+export declare function contractPortal(contract: AppContract): PortalPackage | undefined;
+export declare function portalResource(): Record<string, unknown>;
+/** Every field of DSM's own app.d files; the worker refuses a partial file (synopkg start 272). */
+export declare function renderPortalJson(portal: PortalPackage): string;
+/** DSM's CGI location: index.cgi launches the app id nginx passes as REWRITE_APP. */
+export declare function renderPortalMustache(): string;
+export declare function renderPortalWizardItems(t: Translate, alias: string): Array<Record<string, unknown>>;
+export declare function renderPortalWizardStep(t: Translate, alias: string): InstallWizardStep;
+/**
+ * preinst validates the wizard answer, postinst stores it and writes it as the
+ * default alias of the package's own portal.json, postupgrade restores it into
+ * the new payload. Activation stays an administrator's AppPortal set call.
+ */
+export declare function renderPortalLifecycle(name: string, portal: PortalPackage): string;

package/dist/portal/package.js

@@ -0,0 +1,116 @@
+import { PORTAL_ALIAS_MAX, PORTAL_ALIAS_PATTERN, RESERVED_PORTAL_ALIASES, resolvedContractPortal } from "./alias.js";
+/** Package payload paths DSM's app-portal worker copies to /usr/syno/etc/www/app.d at start. */
+export const PORTAL_JSON_RELPATH = "etc/portal.json";
+export const PORTAL_MUSTACHE_RELPATH = "etc/portal.mustache";
+/** Install wizard key; DSM exports it to preinst/postinst. */
+export const PORTAL_INSTALL_KEY = "portal_alias";
+/** Package-owned install draft, never DSM's saved portal configuration. */
+export const PORTAL_DRAFT = "portal-install.json";
+/** A Compose portal opens the App's `.url` entry of ui/config, keyed by the package id. */
+export function contractPortal(contract) {
+    const portal = resolvedContractPortal(contract);
+    const packageId = String(contract.package);
+    return portal && { appId: packageId, application: String(contract.displayname ?? packageId), alias: portal.alias };
+}
+export function portalResource() {
+    return { "web-config": { "app-portal": { "json-relpath": PORTAL_JSON_RELPATH, "mustache-relpath": PORTAL_MUSTACHE_RELPATH } } };
+}
+/** Every field of DSM's own app.d files; the worker refuses a partial file (synopkg start 272). */
+export function renderPortalJson(portal) {
+    return `${JSON.stringify({
+        application: portal.application,
+        id: portal.appId,
+        alias: portal.alias,
+        fqdn: null,
+        alternatePort: {},
+        "x-accel": false,
+        include: [],
+        injectable: false,
+        ssl: { spdy: false, hsts: false },
+        index: "index.cgi",
+        root: "/usr/syno/synoman",
+        version: 2,
+    })}\n`;
+}
+/** DSM's CGI location: index.cgi launches the app id nginx passes as REWRITE_APP. */
+export function renderPortalMustache() {
+    return "{{> /usr/syno/share/nginx/cgi}}\n";
+}
+/** DSM renders wizard descriptions as HTML; "<alias>" would vanish as a tag. */
+function htmlText(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+export function renderPortalWizardItems(t, alias) {
+    return [
+        { desc: htmlText(t("portal.notice")) },
+        {
+            type: "textfield",
+            desc: t("portal.alias"),
+            subitems: [{
+                    key: PORTAL_INSTALL_KEY,
+                    desc: t("portal.alias"),
+                    defaultValue: alias,
+                    validator: { allowBlank: false, regex: { expr: `/${PORTAL_ALIAS_PATTERN.source}/`, errorText: t("portal.aliasInvalid") } },
+                }],
+        },
+    ];
+}
+export function renderPortalWizardStep(t, alias) {
+    return { step_title: t("portal.step"), items: renderPortalWizardItems(t, alias) };
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+const MARKER = "SYNOPKGLAND_PORTAL_ALIAS";
+/**
+ * preinst validates the wizard answer, postinst stores it and writes it as the
+ * default alias of the package's own portal.json, postupgrade restores it into
+ * the new payload. Activation stays an administrator's AppPortal set call.
+ */
+export function renderPortalLifecycle(name, portal) {
+    if (!["preinst", "postinst", "postupgrade"].includes(name))
+        return "";
+    const [prefix, suffix] = renderPortalJson({ ...portal, alias: MARKER }).trimEnd().split(MARKER);
+    const helpers = `synopkgland_portal_valid() {
+  case "$1" in ''|-*|*-|*[!a-z0-9-]*) return 1 ;; esac
+  [ "\${#1}" -le ${PORTAL_ALIAS_MAX} ] || return 1
+  case ' ${RESERVED_PORTAL_ALIASES.join(" ")} ' in *" $1 "*) return 1 ;; esac
+  return 0
+}
+synopkgland_portal_var="\${SYNOPKG_PKGVAR:-/var/packages/\${SYNOPKG_PKGNAME:-}/var}"
+synopkgland_portal_json="\${SYNOPKG_PKGDEST:-/var/packages/\${SYNOPKG_PKGNAME:-}/target}/${PORTAL_JSON_RELPATH}"
+synopkgland_portal_write() {
+  synopkgland_portal_tmp="$synopkgland_portal_json.$$"
+  printf '%s%s%s\\n' ${shellQuote(prefix)} "$1" ${shellQuote(suffix)} > "$synopkgland_portal_tmp" &&
+    chmod 644 "$synopkgland_portal_tmp" && mv -f "$synopkgland_portal_tmp" "$synopkgland_portal_json"
+}
+`;
+    const answer = `synopkgland_portal_alias="\${${PORTAL_INSTALL_KEY}:-${portal.alias}}"
+  if ! synopkgland_portal_valid "$synopkgland_portal_alias"; then
+    echo "Application Portal alias: use 1-64 lowercase letters, digits or -, not a DSM path." >&2
+    exit 1
+  fi
+`;
+    if (name === "preinst") {
+        return `${helpers}if [ "\${SYNOPKG_PKG_STATUS:-}" != UPGRADE ]; then
+  ${answer}fi
+`;
+    }
+    if (name === "postinst") {
+        return `${helpers}if [ "\${SYNOPKG_PKG_STATUS:-}" != UPGRADE ]; then
+  ${answer}  (umask 077 && mkdir -p "$synopkgland_portal_var" &&
+    printf '{"schema":1,"alias":"%s"}\\n' "$synopkgland_portal_alias" > "$synopkgland_portal_var/.${PORTAL_DRAFT}.$$" &&
+    mv -f "$synopkgland_portal_var/.${PORTAL_DRAFT}.$$" "$synopkgland_portal_var/${PORTAL_DRAFT}") || exit 1
+  synopkgland_portal_write "$synopkgland_portal_alias" || exit 1
+fi
+`;
+    }
+    return `${helpers}synopkgland_portal_draft="$synopkgland_portal_var/${PORTAL_DRAFT}"
+if [ -f "$synopkgland_portal_draft" ] && [ ! -L "$synopkgland_portal_draft" ]; then
+  synopkgland_portal_alias="$(head -c 128 "$synopkgland_portal_draft" | sed -n 's/^{"schema":1,"alias":"\\([a-z0-9-]*\\)"}$/\\1/p')"
+  if synopkgland_portal_valid "$synopkgland_portal_alias"; then
+    synopkgland_portal_write "$synopkgland_portal_alias" || exit 1
+  fi
+fi
+`;
+}