@synopackageland/cli 0.13.1 → 0.15.0

package/dist/build-spk/generator.js

@@ -1,856 +1,12 @@
-import { metadataInfoFields } from "../package-metadata.js";
-import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { createHash } from "node:crypto";
 import * as tar from "tar";
-import { parseDocument, Scalar } from "yaml";
-import { loadContract, collectInstallParameters } from "../contract/load.js";
-import { renderDsmWindowConfig, resolvedWebLaunch, trustedAppEntryPath, usesAuthGateway, } from "../contract/web-launch.js";
-import { buildGatewayBinary, gatewayConfig, writeGatewayPayload } from "./gateway.js";
-import { classifyComposeRoute, loadCompose } from "../compose/analyze.js";
-import { scanComposePrivilege } from "../compose/privilege.js";
-import { validateProject } from "../validate.js";
-import { packageIcons, writeDsmWindowIcons, writePackageCenterIcons } from "./dsm-icons.js";
-import { contractIconPath } from "../contract/icon.js";
-import { infoArchValue, isContainerArchFamily } from "./dsm-arch.js";
-import { assertContainerMinDsm, resolveMinDsm } from "./dsm-version.js";
-import { createReproducibleTar } from "./reproducible-archive.js";
-import { copyProjectNotices } from "./notices.js";
-import { renderDeleteAppDataBlock } from "./delete-app-data.js";
-import { renderUninstallWizardFiles } from "./uninstall-wizard.js";
-import { APP_SCRIPTS_DIR, APP_SCRIPTS_SPK_DIR, composeAppScript, readAppScripts } from "../standalone/app-scripts.js";
-import { renderInstallWizardFiles } from "./install-wizard.js";
-import { renderWizardFiles, writeWizardUiFiles } from "./wizard-i18n.js";
-import { sharedFolderCombobox } from "./share-combobox.js";
-import { writeUiTexts } from "./ui-texts.js";
-import { DSM_LANGS, LOCALES } from "../standalone/i18n.js";
-import { contractAppTitle } from "../contract/i18n.js";
-import { renderHeadlessResourceMarker, renderResourceConfig, renderResourceWorkerStartStopStatus, } from "./resource-worker.js";
-const FILE_MODE = 0o644;
-const SCRIPT_MODE = 0o755;
-const INSTALL_UIFILE = "install_uifile";
-const UPGRADE_UIFILE = "upgrade_uifile";
-const UNINSTALL_UIFILE = "uninstall_uifile";
-const HEADLESS_PROBE_VOLUME = "./.synopkgland:/run/synopkgland:ro";
-const HEADLESS_PROBE_README = "Reserved bind target for package-user headless status probing.\n";
-const SCRIPT_NAMES = [
-    "preinst",
-    "postinst",
-    "preuninst",
-    "postuninst",
-    "preupgrade",
-    "postupgrade",
-    "start-stop-status",
-];
-export async function buildSpk(options) {
-    if (options.archFamily && !isContainerArchFamily(options.archFamily)) {
-        return { ok: false, errors: ["CONTAINER_ARCH_UNSUPPORTED"] };
-    }
-    const validation = validateProject(options.project);
-    if (!validation.ok) {
-        return {
-            ok: false,
-            errors: validation.errors.map((e) => e.code),
-        };
-    }
-    const parsed = loadContract(options.project.contractPath);
-    const contract = { ...parsed.contract };
-    if (options.packageIdentity) {
-        contract.package = options.packageIdentity;
-    }
-    if (options.displayname) {
-        contract.displayname = options.displayname;
-    }
-    if (options.spkVersion) {
-        contract.version = options.spkVersion;
-    }
-    if (options.minDsm !== undefined) {
-        contract.os_min_ver = resolveMinDsm(options.minDsm);
-    }
-    if (options.minDsm !== undefined) {
-        assertContainerMinDsm(String(contract.os_min_ver));
-    }
-    const parsedCompose = loadCompose(options.project.composePath);
-    const route = parsedCompose?.compose
-        ? classifyComposeRoute(contract, parsedCompose)
-        : undefined;
-    if (route && route.errors.length > 0) {
-        return { ok: false, errors: route.errors.map((error) => error.code) };
-    }
-    if (!route || route.route === "reject") {
-        return { ok: false, errors: ["COMPOSE_ROUTE_UNSUPPORTED"] };
-    }
-    const rwEligibility = route.eligibility;
-    const gateway = rwEligibility?.adminport !== undefined && usesAuthGateway(contract)
-        ? gatewayConfig(contract, rwEligibility.adminport)
-        : undefined;
-    if (gateway && !options.archFamily) {
-        return { ok: false, errors: ["GATEWAY_ARCH_FAMILY_REQUIRED"] };
-    }
-    const isDynamicRoute = route?.route === "dynamic";
-    const isResourceWorkerRoute = route?.route === "static-zero-config" ||
-        isDynamicRoute;
-    const icons = packageIcons(contractIconPath(contract, options.project.root));
-    const staging = mkdtempSync(join(tmpdir(), "syno-spk-"));
-    const gatewayWork = mkdtempSync(join(tmpdir(), "syno-gateway-"));
-    try {
-        let gatewayBinary;
-        if (gateway) {
-            const built = await buildGatewayBinary({
-                packageId: String(contract.package),
-                arch: options.archFamily,
-                config: gateway,
-                work: gatewayWork,
-                run: options.gatewayRun,
-            });
-            if ("error" in built) {
-                console.error(built.detail);
-                return { ok: false, errors: [built.error] };
-            }
-            gatewayBinary = built.binary;
-        }
-        writeFileSync(join(staging, "INFO"), renderInfo(contract, options.archFamily, isResourceWorkerRoute), "utf8");
-        writePackageCenterIcons(staging, icons);
-        mkdirSync(join(staging, "conf"), { recursive: true });
-        writeFileSync(join(staging, "conf", "privilege"), renderPrivilege(), "utf8");
-        writeFileSync(join(staging, "privilege"), renderPrivilege(), "utf8");
-        if (isResourceWorkerRoute) {
-            const resourceConfig = renderResourceConfig(contract, rwEligibility, parsedCompose.compose);
-            writeFileSync(join(staging, "conf", "resource"), resourceConfig, "utf8");
-            chmodSync(join(staging, "conf", "resource"), FILE_MODE);
-        }
-        writeWizards(staging, contract, parsedCompose?.compose, "container");
-        mkdirSync(join(staging, "scripts"), { recursive: true });
-        // validateProject already refused a bad scripts/ entry.
-        const appScripts = readAppScripts(options.project.root, () => { }) ?? [];
-        for (const name of SCRIPT_NAMES) {
-            const scriptPath = join(staging, "scripts", name);
-            const script = renderManagedScript(name, contract, isResourceWorkerRoute, rwEligibility?.adminport, isDynamicRoute, rwEligibility?.headless === true);
-            writeFileSync(scriptPath, appScripts.includes(name) ? composeAppScript(name, script) : script, "utf8");
-            chmodSync(scriptPath, SCRIPT_MODE);
-        }
-        for (const name of appScripts) {
-            mkdirSync(join(staging, APP_SCRIPTS_SPK_DIR), { recursive: true });
-            copyFileSync(join(options.project.root, APP_SCRIPTS_DIR, name), join(staging, APP_SCRIPTS_SPK_DIR, name));
-            chmodSync(join(staging, APP_SCRIPTS_SPK_DIR, name), SCRIPT_MODE);
-        }
-        mkdirSync(join(staging, "package"), { recursive: true });
-        copyFileSync(options.project.composePath, join(staging, "package", "compose.yaml"));
-        copyFileSync(options.project.contractPath, join(staging, "package", "synology-app.yaml"));
-        if (isResourceWorkerRoute) {
-            const resourceProjectDir = join(staging, "package", "compose");
-            mkdirSync(resourceProjectDir, { recursive: true });
-            const dsmUserParam = collectInstallParameters(contract).find((p) => p.param.type === "dsm_user");
-            let composeContent;
-            if (dsmUserParam || rwEligibility?.headless === true) {
-                const rawYaml = readFileSync(options.project.composePath, "utf8");
-                const doc = parseDocument(rawYaml);
-                const services = doc.get("services");
-                if (dsmUserParam && services && typeof services === "object" && typeof services.toJSON === "function") {
-                    const serviceNames = Object.keys(services.toJSON());
-                    for (const sName of serviceNames) {
-                        const userVal = new Scalar(`\${${dsmUserParam.name}_UID}:\${${dsmUserParam.name}_GID}`);
-                        userVal.type = Scalar.QUOTE_DOUBLE;
-                        doc.setIn(["services", sName, "user"], userVal);
-                    }
-                }
-                if (rwEligibility?.headless === true) {
-                    injectHeadlessProbeVolume(doc);
-                }
-                composeContent = doc.toString();
-                if (dsmUserParam) {
-                    const escaped = `\\$\\{${dsmUserParam.name}_UID\\}:\\$\\{${dsmUserParam.name}_GID\\}`;
-                    composeContent = composeContent.replace(new RegExp(`^([ \\t]*)user:\\s*"${escaped}"`, "gm"), `$1user: "\${${dsmUserParam.name}_UID}:\${${dsmUserParam.name}_GID}"\n$1# synopkgland:group_add ${dsmUserParam.name}`);
-                }
-            }
-            else {
-                composeContent = readFileSync(options.project.composePath, "utf8");
-            }
-            composeContent = injectPosixAllSharesMarkers(composeContent, contract);
-            writeFileSync(join(resourceProjectDir, "docker-compose.yml"), composeContent, "utf8");
-            chmodSync(join(resourceProjectDir, "docker-compose.yml"), FILE_MODE);
-            if (rwEligibility?.headless === true) {
-                const probePayloadDir = join(resourceProjectDir, ".synopkgland");
-                mkdirSync(probePayloadDir, { recursive: true });
-                writeFileSync(join(probePayloadDir, "README"), HEADLESS_PROBE_README, "utf8");
-                chmodSync(join(probePayloadDir, "README"), FILE_MODE);
-            }
-        }
-        const htmlDir = join(options.project.root, "html");
-        if (existsSync(htmlDir)) {
-            cpSync(htmlDir, join(staging, "package", "html"), { recursive: true });
-            if (isResourceWorkerRoute) {
-                cpSync(htmlDir, join(staging, "package", "compose", "html"), { recursive: true });
-            }
-        }
-        if (contract.adminport !== undefined && resolvedWebLaunch(contract) === "dsm-window") {
-            const uiDir = join(staging, "package", "ui");
-            mkdirSync(uiDir, { recursive: true });
-            writeFileSync(join(uiDir, "config"), renderDsmWindowConfig(contract, icons), "utf8");
-            writeDsmWindowIcons(uiDir, icons);
-            writeUiTexts(uiDir, contractAppTitle(contract));
-        }
-        if (gateway && gatewayBinary) {
-            writeGatewayPayload(join(staging, "package"), gatewayBinary, gateway);
-        }
-        chmodSync(join(staging, "INFO"), FILE_MODE);
-        chmodSync(join(staging, "privilege"), FILE_MODE);
-        chmodSync(join(staging, "package", "compose.yaml"), FILE_MODE);
-        chmodSync(join(staging, "package", "synology-app.yaml"), FILE_MODE);
-        if (contract.adminport !== undefined && resolvedWebLaunch(contract) === "dsm-window") {
-            chmodSync(join(staging, "package", "ui", "config"), FILE_MODE);
-        }
-        const outputPath = options.outputPath ?? join(options.project.root, `${String(contract.package)}.spk`);
-        copyProjectNotices(options.project.root, join(staging, 'package'));
-        await createDeterministicSpk(staging, outputPath);
-        return { ok: true, outputPath, errors: [] };
-    }
-    finally {
-        rmSync(staging, { recursive: true, force: true });
-        rmSync(gatewayWork, { recursive: true, force: true });
-    }
-}
-function quoteInfo(value) {
-    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-function spkVersion(version) {
-    return /-\d+$/.test(version) ? version : `${version}-0001`;
-}
-function renderInfo(contract, archFamily, isResourceWorker = false) {
-    const lines = [];
-    const add = (key, value) => {
-        lines.push(`${key}=${quoteInfo(String(value))}`);
-    };
-    add("package", String(contract.package));
-    add("version", spkVersion(String(contract.version)));
-    add("displayname", String(contract.displayname));
-    add("description", String(contract.description));
-    add("maintainer", String(contract.maintainer));
-    const info = contractAppTitle(contract).info;
-    for (const locale of LOCALES) {
-        const text = info?.[locale];
-        if (text?.displayname)
-            add(`displayname_${DSM_LANGS[locale]}`, text.displayname);
-        if (text?.description)
-            add(`description_${DSM_LANGS[locale]}`, text.description);
-    }
-    for (const [key, value] of metadataInfoFields(contract.metadata))
-        add(key, value);
-    add("arch", archFamily === undefined ? "noarch" : infoArchValue(archFamily));
-    add("os_min_ver", String(contract.os_min_ver));
-    const viaGateway = isResourceWorker && usesAuthGateway(contract);
-    if (isResourceWorker) {
-        // DSM reports Container Manager as "not ready" through the package
-        // dependency gate even while pkgctl-ContainerManager is running. The
-        // docker-project worker itself remains the authoritative live prerequisite
-        // (ContainerManager >= 1432); keep only the reliable Web Station package
-        // dependency here so a valid resource-worker SPK can reach acquisition.
-        // A gateway package has no Web Station portal, so it does not depend on it.
-        if (contract.adminport !== undefined && !viaGateway) {
-            add("install_dep_packages", "WebStation");
-        }
-    }
-    add("startable", "yes");
-    const launch = resolvedWebLaunch(contract);
-    if (contract.adminprotocol && !viaGateway) {
-        add("adminprotocol", String(contract.adminprotocol));
-    }
-    if (launch === "new-page" || launch === "dsm-window") {
-        // Package Center Open uses INFO.adminurl as a same-host path. Do not emit
-        // adminport — that would open the Compose published port (ADR-0053/0062).
-        add("adminurl", trustedAppEntryPath(contract));
-    }
-    else {
-        if (contract.adminport !== undefined) {
-            add("adminport", Number(contract.adminport));
-            // DSM checkport=yes treats INFO.adminport as exclusive. Compose also binds
-            // that host port, so a matching adminport yields synopkg 283 — including
-            // when the same App's container already holds the port. ADR-0053: the
-            // published port is the Web Station upstream, not Package Center Open.
-            add("checkport", "no");
-        }
-        if (contract.adminurl) {
-            add("adminurl", String(contract.adminurl));
-        }
-    }
-    if (launch === "dsm-window") {
-        add("dsmuidir", "ui");
-        add("dsmappname", String(contract.package));
-    }
-    else if (viaGateway) {
-        // The gateway CGI is served from ui/ even when the App opens in a new page.
-        add("dsmuidir", "ui");
-    }
-    return `${lines.join("\n")}\n`;
-}
-function renderPrivilege() {
-    return `${JSON.stringify({
-        defaults: {
-            "run-as": "package",
-        },
-    }, null, 2)}\n`;
-}
-function volumeSources(compose) {
-    return volumeMounts(compose).map((mount) => mount.source);
-}
-function volumeMounts(compose) {
-    const mounts = [];
-    for (const service of Object.values(compose.services ?? {})) {
-        const volumes = service.volumes;
-        if (!volumes) {
-            continue;
-        }
-        const entries = Array.isArray(volumes) ? volumes : [volumes];
-        for (const entry of entries) {
-            if (typeof entry === "string") {
-                const parts = entry.split(":");
-                const source = parts[0]?.trim() ?? "";
-                if (source) {
-                    const modes = parts
-                        .slice(2)
-                        .flatMap((part) => part.split(","))
-                        .map((part) => part.trim());
-                    mounts.push({ source, readOnly: modes.includes("ro") });
-                }
-            }
-            else if (entry && typeof entry === "object" && "source" in entry) {
-                const record = entry;
-                const source = String(record.source ?? "").trim();
-                if (source) {
-                    mounts.push({ source, readOnly: record.read_only === true });
-                }
-            }
-        }
-    }
-    return mounts;
-}
-// A Compose that mounts nothing reaches even less of the NAS than one that
-// mounts only PKGVAR, so it earns the same consent line. Returning false for
-// zero sources left the wizard step with no items at all, and DSM's Package
-// Center rejects that SPK with "Invalid file format".
-function composeUsesOnlyAppSpace(compose) {
-    const sources = volumeSources(compose);
-    return sources.every((source) => source.startsWith("${SYNOPKG_PKGVAR}") || source.startsWith("${SYNO_APP_SECRETS_DIR}"));
-}
-function injectHeadlessProbeVolume(doc) {
-    const compose = (doc.toJSON() ?? {});
-    const serviceName = Object.keys(compose.services ?? {})[0];
-    if (!serviceName) {
-        return;
-    }
-    const existingVolumes = compose.services?.[serviceName]?.volumes;
-    const volumes = existingVolumes == null
-        ? []
-        : Array.isArray(existingVolumes)
-            ? [...existingVolumes]
-            : [existingVolumes];
-    if (!volumes.some((volume) => volume === HEADLESS_PROBE_VOLUME)) {
-        volumes.push(HEADLESS_PROBE_VOLUME);
-    }
-    doc.setIn(["services", serviceName, "volumes"], volumes);
-}
-function injectPosixAllSharesMarkers(composeContent, contract) {
-    const names = collectInstallParameters(contract)
-        .filter(({ param }) => param.type === "posix_all_shares")
-        .map(({ name }) => name);
-    if (names.length === 0) {
-        return composeContent;
-    }
-    const declared = new Set(names);
-    const lines = composeContent.split("\n");
-    const output = [];
-    for (const line of lines) {
-        const match = line.match(/^(\s*)-\s*["']?\$\{([A-Za-z_][A-Za-z0-9_]*)\}:/);
-        const name = match?.[2];
-        if (match && name && declared.has(name)) {
-            const marker = `# synopkgland:posix_all_shares ${name}`;
-            if (output.at(-1)?.trim() !== marker) {
-                output.push(`${match[1]}${marker}`);
-            }
-        }
-        output.push(line);
-    }
-    return output.join("\n");
-}
-function renderInstallWizard(t, contract, compose) {
-    const items = [];
-    const params = collectInstallParameters(contract);
-    const hasSharedFolder = params.some((item) => item.param.type === "shared_folder");
-    const hasHomes = params.some((item) => item.param.type === "homes");
-    const hasDsmUser = params.some((item) => item.param.type === "dsm_user");
-    if (compose && scanComposePrivilege(compose).length > 0) {
-        items.push({
-            desc: t("consent.privilege"),
-        });
-    }
-    if (hasSharedFolder) {
-        items.push({
-            desc: t("consent.sharedFolder"),
-        });
-    }
-    if (hasHomes) {
-        items.push({
-            desc: t("consent.homes"),
-        });
-    }
-    if (hasDsmUser) {
-        items.push({
-            desc: t("consent.dsmUser"),
-        });
-    }
-    if (!hasSharedFolder && (!compose || composeUsesOnlyAppSpace(compose))) {
-        items.push({
-            desc: t("consent.appOwnSpace"),
-        });
-    }
-    for (const { name, param } of params) {
-        if (param.type === "secret" && param.generate === true) {
-            continue;
-        }
-        if (param.type === "string") {
-            items.push({
-                type: "textfield",
-                desc: t("param.install", { name }),
-                subitems: [{
-                        key: name,
-                        desc: name,
-                        defaultValue: param.default ?? "",
-                        validator: { allowBlank: false },
-                    }],
-            });
-            continue;
-        }
-        if (param.type === "boolean") {
-            items.push({
-                type: "multiselect",
-                desc: t("param.install", { name }),
-                subitems: [{ key: name, desc: name, defaultValue: param.default ?? false }],
-            });
-            continue;
-        }
-        if (param.type === "secret") {
-            items.push({
-                type: "password",
-                desc: t("param.install", { name }),
-                subitems: [{ key: name, desc: name, validator: { allowBlank: false } }],
-            });
-            continue;
-        }
-        if (param.type === "shared_folder") {
-            items.push(sharedFolderCombobox(t, name));
-            continue;
-        }
-        if (param.type === "posix_all_shares") {
-            // A47 (install side): DSM's declarative wizard only ever renders a
-            // single-select combo here, so the former multiSelect control silently
-            // mounted exactly one Share instead of every Share. Package Center can
-            // therefore never carry the full Share list, and there is no honest
-            // control to render -- so this branch produces only an informational
-            // textblock. The full snapshot arrives exclusively via CLI
-            // extra_values (`synopkgland deploy`), which the preinst materializer
-            // expands. No subitem key is emitted, so the install uifile contains no
-            // ALL_SHARES and no CHANGE_ALL_SHARES.
-            items.push({
-                type: "textblock",
-                desc: t("consent.posixAllShares"),
-            });
-            continue;
-        }
-        if (param.type === "dsm_user") {
-            items.push({
-                type: "combobox",
-                desc: t("param.runAs", { name }),
-                subitems: [{
-                        key: name,
-                        desc: name,
-                        displayField: "name",
-                        valueField: "name",
-                        editable: false,
-                        forceSelection: true,
-                        autoSelect: false,
-                        mode: "remote",
-                        api_store: {
-                            api: "SYNO.Core.User",
-                            method: "list",
-                            version: 1,
-                            baseParams: { limit: -1, offset: 0 },
-                            root: "users",
-                            idProperty: "name",
-                            fields: ["name"],
-                        },
-                        validator: { allowBlank: false },
-                    }],
-            });
-        }
-    }
-    return [{
-            step_title: t("install.step"),
-            items,
-        }];
-}
-function renderUpgradeWizard(t, contract, compose) {
-    const installWizard = renderInstallWizard(t, contract, compose);
-    const params = collectInstallParameters(contract);
-    // Every type whose value must survive an upgrade the administrator did not
-    // deliberately change. Two mechanisms are needed because DSM renders them
-    // differently: a control that can be left blank just allows blank, while one
-    // that always carries a value needs an explicit "change this" gate.
-    //   - dsm_user  : blank in some layouts, but measured on DSM 7.4-90069 with
-    //                 Shared Folder controls beside it to come up pre-filled with a
-    //                 Shared Folder name, so it needs the same explicit gate
-    //   - string    : blank once the new version's default is withheld (A44)
-    //   - shared_folder : DSM prefills the first store row
-    //   - boolean   : a checkbox has no blank state at all
-    // posix_all_shares is intentionally absent: it renders as a textblock with
-    // no subitem, so there is nothing to blank or gate on the upgrade wizard.
-    // Its value can only arrive via CLI extra_values, and the preinst
-    // change-gate shell (`upgrade_change_enabled`, `CHANGE_<name>`) still
-    // governs that path, reusing the canonical snapshot on an untouched upgrade.
-    const upgradeReuseTypes = new Map(params
-        .filter(({ param }) => param.type === "shared_folder" ||
-        param.type === "dsm_user" ||
-        param.type === "string" ||
-        param.type === "boolean")
-        .map(({ name, param }) => [name, param.type]));
-    const needsChangeGate = (type) => type === "shared_folder" || type === "dsm_user" || type === "boolean";
-    const upgradeItems = installWizard[0].items.flatMap((item) => {
-        if (!Array.isArray(item.subitems)) {
-            return [item];
-        }
-        const reuseKeys = [];
-        const subitems = item.subitems.map((subitem) => {
-            if (!subitem || typeof subitem !== "object") {
-                return subitem;
-            }
-            const record = subitem;
-            if (typeof record.key !== "string" || !upgradeReuseTypes.has(record.key)) {
-                return subitem;
-            }
-            reuseKeys.push(record.key);
-            const reused = {
-                ...record,
-                validator: { allowBlank: true },
-            };
-            // Withholding the default is what makes an untouched upgrade blank, and
-            // blank is what lets preinst fall through to the canonical .env value.
-            // Install keeps the default -- only this upgrade copy drops it.
-            delete reused.defaultValue;
-            return reused;
-        });
-        if (reuseKeys.length === 0) {
-            return [item];
-        }
-        const control = {
-            ...item,
-            desc: t("upgrade.reuseDesc", { desc: String(item.desc ?? "") }),
-            subitems,
-        };
-        const changeControls = reuseKeys
-            .filter((key) => needsChangeGate(upgradeReuseTypes.get(key)))
-            .map((key) => {
-            const type = upgradeReuseTypes.get(key);
-            const label = type === "shared_folder"
-                ? t("label.sharedFolder")
-                : type === "dsm_user"
-                    ? t("label.runAs")
-                    : key;
-            return {
-                type: "multiselect",
-                desc: t("upgrade.changeDesc", { label }),
-                subitems: [{
-                        key: `CHANGE_${key}`,
-                        desc: t("upgrade.changeSub", { label }),
-                        defaultValue: false,
-                    }],
-            };
-        });
-        return [...changeControls, control];
-    });
-    const sharedFolderNames = params
-        .filter((item) => item.param.type === "shared_folder")
-        .map((item) => item.name);
-    const hasSharedFolder = sharedFolderNames.length > 0;
-    const hasDsmUser = params.some((item) => item.param.type === "dsm_user");
-    const hasReadWriteSharedFolder = hasSharedFolder &&
-        compose !== undefined &&
-        volumeMounts(compose).some((mount) => !mount.readOnly &&
-            sharedFolderNames.some((name) => mount.source === `\${${name}}` || mount.source.startsWith(`\${${name}}/`)));
-    const upgradeConsent = [];
-    const posixAllSharesNames = params
-        .filter((item) => item.param.type === "posix_all_shares")
-        .map((item) => item.name);
-    if (posixAllSharesNames.length > 0) {
-        upgradeConsent.push({
-            desc: t("upgrade.posixNotice"),
-        });
-    }
-    if (hasReadWriteSharedFolder) {
-        upgradeConsent.push({
-            desc: t("upgrade.sharedFolderRw"),
-        });
-    }
-    if (hasDsmUser && hasSharedFolder) {
-        upgradeConsent.push({
-            desc: t("upgrade.dsmUser"),
-        });
-    }
-    if (upgradeConsent.length === 0) {
-        return [{
-                ...installWizard[0],
-                step_title: t("upgrade.step"),
-                items: upgradeItems,
-            }];
-    }
-    const firstControl = upgradeItems.findIndex((item) => item.subitems !== undefined);
-    const insertAt = firstControl === -1 ? upgradeItems.length : firstControl;
-    const items = [...upgradeItems];
-    items.splice(insertAt, 0, ...upgradeConsent);
-    return [{
-            ...installWizard[0],
-            step_title: t("upgrade.step"),
-            items,
-        }];
-}
-function writeWizards(staging, contract, compose, kind) {
-    const install = renderInstallWizardFiles(String(contract.package), (t) => renderInstallWizard(t, contract, compose));
-    writeWizardUiFiles(staging, {
-        ...install.static,
-        ...install.dynamic,
-        ...renderWizardFiles(UPGRADE_UIFILE, (t) => renderUpgradeWizard(t, contract, compose)),
-        ...renderUninstallWizardFiles(String(contract.package), kind),
-    });
-}
-function renderDynamicPreinstMaterializer(contract) {
-    const allParams = collectInstallParameters(contract);
-    const scalarParams = allParams.filter(({ param }) => param.type === "string" || param.type === "boolean");
-    const sharedFolderParams = allParams.filter(({ param }) => param.type === "shared_folder");
-    const posixAllSharesParams = allParams.filter(({ param }) => param.type === "posix_all_shares");
-    const dsmUserParam = allParams.find(({ param }) => param.type === "dsm_user");
-    const lines = [
-        "#!/bin/sh",
-        "set -eu",
-        "umask 077",
-        "# D3/D5.4 package-only carrier; values are wizard answers, canonical values, or defaults.",
-        "die() { echo \"dynamic route materialization failed: $1\" >&2; exit 1; }",
-        'T="${SYNOPKG_PKGINST_TEMP_DIR:?}"',
-        'STATUS="${SYNOPKG_PKG_STATUS:?}"',
-        'PROJECT="$T/compose"',
-        'RUNTIME_ENV="$PROJECT/.env"',
-        'CANONICAL_ENV="${SYNOPKG_PKGDEST_VOL:?}/@appdata/${SYNOPKG_PKGNAME:?}/.env"',
-        'PLATFORM_PKGVAR="${SYNOPKG_PKGDEST_VOL:?}/@appdata/${SYNOPKG_PKGNAME:?}"',
-        'PLATFORM_SECRETS="${SYNOPKG_PKGDEST_VOL:?}/@apphome/${SYNOPKG_PKGNAME:?}/secrets"',
-        '[ -d "$PROJECT" ] || die "compose directory is missing"',
-        '[ ! -L "$PROJECT" ] || die "compose directory is a symlink"',
-        '[ "$(stat -c %u "$PROJECT")" = "$(id -u)" ] || die "compose directory owner is not the package user"',
-        '[ ! -L "$RUNTIME_ENV" ] || die "runtime file is a symlink"',
-        'if [ -e "$RUNTIME_ENV" ] && [ ! -f "$RUNTIME_ENV" ]; then die "runtime path is not a regular file"; fi',
-        "read_env_value() {",
-        "  file=\"$1\"",
-        "  key=\"$2\"",
-        "  awk -F= -v key=\"$key\" '$1 == key { value=substr($0, index($0,\"=\")+1); if (value ~ /^\".*\"$/) value=substr(value,2,length(value)-2); print value; found=1; exit } END { if (!found) exit 1 }' \"$file\"",
-        "}",
-        "append_env() {",
-        "  key=\"$1\"",
-        "  value=\"$2\"",
-        "  type=\"${3:-string}\"",
-        "  if printf '%s' \"$value\" | LC_ALL=C grep -q '[[:cntrl:]]'; then",
-        "    die \"control character in environment value $key\"",
-        "  fi",
-        "  case \"$value\" in",
-        "    *[[:cntrl:]]*) die \"control character in environment value $key\" ;;",
-        "  esac",
-        "  if [ \"$type\" = \"boolean\" ]; then",
-        "    normalized=\"$(printf '%s' \"$value\" | LC_ALL=C tr '[:upper:]' '[:lower:]')\"",
-        "    case \"$normalized\" in",
-        "      true|false) value=\"$normalized\" ;;",
-        "      *) die \"invalid boolean value $key\" ;;",
-        "    esac",
-        "  fi",
-        "  case \"$value\" in",
-        "    *[!A-Za-z0-9_./:@-]*)",
-        "      escaped=\"$(printf '%s' \"$value\" | sed 's/\\\\/\\\\\\\\/g; s/\"/\\\\\"/g')\"",
-        "      printf '%s=\"%s\"\\n' \"$key\" \"$escaped\"",
-        "      ;;",
-        "    *) printf '%s=%s\\n' \"$key\" \"$value\" ;;",
-        "  esac",
-        "}",
-    ];
-    // Emitted whenever anything reads a CHANGE_ gate. Boolean parameters (A44) use
-    // it too, and a package with only booleans has no Share resolvers -- leaving it
-    // behind that condition made `! upgrade_change_enabled ...` a missing command,
-    // which is true, so the gate silently always reused the canonical value.
-    const usesUpgradeChangeGate = sharedFolderParams.length > 0 ||
-        posixAllSharesParams.length > 0 ||
-        collectInstallParameters(contract).some(({ param }) => param.type === "boolean" || param.type === "dsm_user");
-    if (usesUpgradeChangeGate) {
-        lines.push("upgrade_change_enabled() {", "  normalized=\"$(printf '%s' \"$1\" | LC_ALL=C tr '[:upper:]' '[:lower:]')\"", "  case \"$normalized\" in", "    true|1|yes|on) return 0 ;;", "    *) return 1 ;;", "  esac", "}");
-    }
-    if (sharedFolderParams.length > 0 || posixAllSharesParams.length > 0) {
-        lines.push("resolve_shared_folder() {", "  share_name=\"$1\"", "  case \"$share_name\" in", "    */*|*..*) die \"invalid share name $share_name\" ;;", "    '') die \"share name is empty\" ;;", "  esac", "  mounts_file=\"${D54_MOUNTS_FILE:-/proc/mounts}\"", "  if [ ! -r \"$mounts_file\" ] && [ -r \"/etc/mtab\" ]; then", "    mounts_file=\"/etc/mtab\"", "  fi", "  if [ ! -r \"$mounts_file\" ]; then", "    die \"cannot read mount points from $mounts_file\"", "  fi", "  vols=\"$(awk '$2 ~ /^\\/volume[0-9]+$/ {print $2}' \"$mounts_file\" | sort -u)\"", '  if [ -z "$vols" ]; then', "    vols=\"$(awk '{print $2}' \"$mounts_file\" | sort -u)\"", "  fi", "  matched=\"\"", "  count=0", "  for v in $vols; do", "    if [ -d \"$v/$share_name\" ]; then", "      matched=\"$v/$share_name\"", "      count=$((count + 1))", "    fi", "  done", "  if [ \"$count\" -eq 0 ]; then", "    die \"share $share_name not found on any volume\"", "  elif [ \"$count\" -gt 1 ]; then", "    die \"share $share_name matched multiple volumes\"", "  fi", "  printf '%s' \"$matched\"", "}");
-    }
-    if (posixAllSharesParams.length > 0) {
-        lines.push("normalize_posix_all_shares() {", "  value=\"$1\"", "  case \"$value\" in", "    \\[*\\]) value=\"$(printf '%s' \"$value\" | sed 's/^[[:space:]]*\\[//; s/\\][[:space:]]*$//; s/\"//g')\" ;;", "  esac", "  printf '%s' \"$value\" | awk -F, '{ for (i = 1; i <= NF; i++) { gsub(/^[ \\t]+|[ \\t]+$/, \"\", $i); if ($i != \"\") print $i } }'", "}", "resolve_posix_all_shares() {", "  raw_list=\"$1\"", "  normalized=\"$(normalize_posix_all_shares \"$raw_list\")\"", "  [ -n \"$normalized\" ] || die \"POSIX_ALL_SHARES_EMPTY\"", "  names=\"\"", "  paths=\"\"", "  count=0", "  while IFS= read -r share_name; do", "    case \"$share_name\" in", "      */*|*..*|@*|'') die \"invalid Share name $share_name\" ;;", "      *[[:cntrl:]]*) die \"invalid Share name $share_name\" ;;", "    esac", "    share_path=\"$(resolve_shared_folder \"$share_name\")\"", "    names=\"${names}${names:+,}${share_name}\"", "    paths=\"${paths}${paths:+,}${share_path}\"", "    count=$((count + 1))", "  done <<EOF", "$normalized", "EOF", "  [ \"$count\" -gt 0 ] || die \"POSIX_ALL_SHARES_EMPTY\"", "  printf '%s\\n%s\\n%s' \"$names\" \"$paths\" \"$count\"", "}", "rewrite_posix_all_shares() {", "  p_name=\"$1\"", "  share_names=\"$2\"", "  share_paths=\"$3\"", "  compose_file=\"$4\"", "  [ -f \"$compose_file\" ] || die \"compose file missing at $compose_file\"", "  [ ! -L \"$compose_file\" ] || die \"compose file is a symlink\"", "  tmp_compose=\"$(mktemp \"${compose_file}.tmp.XXXXXX\")\"", "  awk -v param=\"$p_name\" -v share_names=\"$share_names\" -v share_paths=\"$share_paths\" '", "    BEGIN {", "      name_count = split(share_names, names, \",\")", "      path_count = split(share_paths, paths, \",\")", "      marker = \"# synopkgland:posix_all_shares \" param", "      pending = 0", "      single_quote = sprintf(\"%c\", 39)", "    }", "    {", "      if (index($0, marker) > 0 && $0 ~ /^[ \\t]*# synopkgland:posix_all_shares /) {", "        print $0", "        pending = 1", "        next", "      }", "      if (!pending) { print $0; next }", "      pending = 0", "      line = $0", "      indent = line", "      sub(/[^ \\t].*$/, \"\", indent)", "      entry = line", "      sub(/^[ \\t]*-[ \\t]*/, \"\", entry)", "      if (entry ~ /^\".*\"$/) entry = substr(entry, 2, length(entry) - 2)", "      if (length(entry) >= 2 && substr(entry, 1, 1) == single_quote && substr(entry, length(entry), 1) == single_quote) entry = substr(entry, 2, length(entry) - 2)", "      split(entry, fields, \":\")", "      if (fields[1] != \"${\" param \"}\" || fields[2] == \"\") { print $0; next }", "      mode = \"\"", "      if (length(fields) >= 3) mode = \":\" fields[3]", "      for (i = 1; i <= name_count && i <= path_count; i++) {", "        print indent \"- \" paths[i] \":\" fields[2] \"/\" names[i] mode", "      }", "    }", "  ' \"$compose_file\" > \"$tmp_compose\" || die \"failed to expand POSIX all-shares in $compose_file\"", "  mv \"$tmp_compose\" \"$compose_file\" || die \"failed to replace $compose_file\"", "}");
-    }
-    if (dsmUserParam) {
-        lines.push("resolve_dsm_user() {", "  user_name=\"$1\"", "  case \"$user_name\" in", "    */*|*..*|*[[:cntrl:]]*) die \"invalid user name $user_name\" ;;", "    '') die \"user name is empty\" ;;", "  esac", "  u_uid=\"$(id -u -- \"$user_name\" 2>/dev/null || true)\"", "  case \"$u_uid\" in", "    ''|*[!0-9]*) die \"resolved uid for $user_name is not a valid integer\" ;;", "    0) die \"resolved uid for $user_name cannot be 0 (root)\" ;;", "  esac", "  u_gid=\"$(id -g -- \"$user_name\" 2>/dev/null || true)\"", "  case \"$u_gid\" in", "    ''|*[!0-9]*) die \"resolved gid for $user_name is not a valid integer\" ;;", "  esac", "  # id -G returns all group ids including primary", "  raw_groups=\"$(id -G -- \"$user_name\" 2>/dev/null || true)\"", "  # filter out primary gid, deduplicate, keep numeric only", "  supp_groups=\"\"", "  for g in $raw_groups; do", "    case \"$g\" in", "      ''|*[!0-9]*) continue ;;", "    esac", "    if [ \"$g\" != \"$u_gid\" ]; then", "      already=0", "      for sg in $supp_groups; do", "        if [ \"$sg\" = \"$g\" ]; then", "          already=1", "          break", "        fi", "      done", "      if [ \"$already\" -eq 0 ]; then", "        supp_groups=\"${supp_groups}${supp_groups:+ }$g\"", "      fi", "    fi", "  done", "  printf '%s %s %s' \"$u_uid\" \"$u_gid\" \"$supp_groups\"", "}", "rewrite_group_add() {", "  p_name=\"$1\"", "  g_list=\"$2\"", "  compose_file=\"$3\"", "  [ -f \"$compose_file\" ] || die \"compose file missing at $compose_file\"", "  [ ! -L \"$compose_file\" ] || die \"compose file is a symlink\"", "  tmp_compose=\"$(mktemp \"${compose_file}.tmp.XXXXXX\")\"", "  awk -v param=\"$p_name\" -v g_list=\"$g_list\" '", "    BEGIN {", "      n = split(g_list, g_arr, \" \")", "    }", "    {", "      regex = \"^[ \\t]*# synopkgland:group_add \" param \"$\"", "      if ($0 ~ regex) {", "        match($0, /^[ \\t]*/)", "        indent = substr($0, RSTART, RLENGTH)", "        if (n > 0) {", "          print indent \"group_add:\"", "          for (i = 1; i <= n; i++) {", "            print indent \"  - ${\" param \"_GROUP_\" i \"}\"", "          }", "        }", "      } else {", "        print $0", "      }", "    }", "  ' \"$compose_file\" > \"$tmp_compose\" || die \"failed to rewrite group_add in $compose_file\"", "  mv \"$tmp_compose\" \"$compose_file\" || die \"failed to replace $compose_file\"", "}");
-    }
-    lines.push('tmp="$(mktemp "$PROJECT/.env.tmp.XXXXXX")"', 'chmod 600 "$tmp"', '[ "$(stat -c %a "$tmp")" = "600" ] || die "temporary env mode is not 0600"', '[ "$(stat -c %u "$tmp")" = "$(id -u)" ] || die "temporary env owner is not the package user"', "trap 'rm -f \"$tmp\"' EXIT HUP INT TERM", "{");
-    const valueVars = [];
-    for (const { name, param } of scalarParams) {
-        const type = param.type;
-        const valueVar = "D3_VALUE_" + name;
-        valueVars.push({ name, valueVar, type });
-        const fallback = param.default !== undefined
-            ? String(param.default)
-            : type === "boolean"
-                ? "false"
-                : "";
-        // A44: on UPGRADE the wizard always submits something for these controls, so
-        // "was it submitted" cannot mean "did the administrator choose it". A blank
-        // string, or a boolean whose CHANGE_ gate is unchecked, means "keep what is
-        // installed" -- otherwise the new version's default would silently replace a
-        // value chosen at install time. INSTALL is unaffected: STATUS is not UPGRADE,
-        // so the reuse branch is skipped and the default still applies.
-        const reuseGuard = type === "boolean"
-            ? `! upgrade_change_enabled "\${CHANGE_${name}:-}"`
-            : `[ -z "\${${name}:-}" ]`;
-        lines.push(`  if [ "$STATUS" = "UPGRADE" ] && ${reuseGuard} && [ -f "$CANONICAL_ENV" ] && ` +
-            `[ ! -L "$CANONICAL_ENV" ] && ${valueVar}="$(read_env_value "$CANONICAL_ENV" "${name}")"; then`, "    :", `  elif [ "\${${name}+x}" = x ]; then`, `    ${valueVar}="\${${name}}"`, '  elif [ "$STATUS" = "UPGRADE" ] && [ -f "$CANONICAL_ENV" ] && [ ! -L "$CANONICAL_ENV" ] && ' +
-            `${valueVar}="$(read_env_value "$CANONICAL_ENV" "${name}")"; then`, "    :", "  else", "    " + valueVar + "=" + shellQuote(fallback), "  fi");
-    }
-    const shareVars = [];
-    for (const { name } of sharedFolderParams) {
-        const rawVar = "D54_RAW_SHARE_" + name;
-        const pathVar = "D54_RESOLVED_PATH_" + name;
-        const changeVar = "CHANGE_" + name;
-        shareVars.push({ name, pathVar });
-        lines.push(`  if [ "$STATUS" = "UPGRADE" ] && upgrade_change_enabled "\${${changeVar}:-}"; then`, `    if [ "\${${name}+x}" = x ] && [ -n "\${${name}}" ]; then`, `      ${rawVar}="\${${name}}"`, "    else", `      die "missing required shared folder parameter ${name}"`, "    fi", '  elif [ "$STATUS" = "UPGRADE" ] && [ -f "$CANONICAL_ENV" ] && [ ! -L "$CANONICAL_ENV" ] && ' +
-            `${rawVar}="$(read_env_value "$CANONICAL_ENV" "${name}")"; then`, "    :", '  elif [ "$STATUS" = "UPGRADE" ]; then', `    die "missing canonical shared folder parameter ${name}"`, `  elif [ "\${${name}+x}" = x ]; then`, `    ${rawVar}="\${${name}}"`, "  else", `    die "missing required shared folder parameter ${name}"`, "  fi", `  case "$${rawVar}" in`, "    /*) " + pathVar + "=\"$" + rawVar + "\" ;;", "    *) " + pathVar + "=\"$(resolve_shared_folder \"$" + rawVar + "\")\" ;;", "  esac");
-    }
-    const posixVars = [];
-    for (const { name } of posixAllSharesParams) {
-        const rawVar = "D54_RAW_POSIX_" + name;
-        const namesVar = "D54_POSIX_NAMES_" + name;
-        const pathsVar = "D54_POSIX_PATHS_" + name;
-        const countVar = "D54_POSIX_COUNT_" + name;
-        const changeVar = "CHANGE_" + name;
-        posixVars.push({ name, namesVar, pathsVar, countVar });
-        lines.push(`  if [ "$STATUS" = "UPGRADE" ] && upgrade_change_enabled "\${${changeVar}:-}"; then`, `    if [ "\${${name}+x}" = x ] && [ -n "\${${name}}" ]; then`, `      ${rawVar}="\${${name}}"`, "    else", `      die "missing required POSIX all-shares parameter ${name}"`, "    fi", '  elif [ "$STATUS" = "UPGRADE" ] && [ -f "$CANONICAL_ENV" ] && [ ! -L "$CANONICAL_ENV" ] && ' +
-            `${rawVar}="$(read_env_value "$CANONICAL_ENV" "${name}")"; then`, "    :", '  elif [ "$STATUS" = "UPGRADE" ]; then', `    die "missing canonical POSIX all-shares parameter ${name}"`, `  elif [ "\${${name}+x}" = x ]; then`, `    ${rawVar}="\${${name}}"`, "  else", `    die "missing required POSIX all-shares parameter ${name}"`, "  fi", `  posix_info="$(resolve_posix_all_shares "$${rawVar}")"`, `  ${namesVar}="$(printf '%s\\n' "$posix_info" | sed -n '1p')"`, `  ${pathsVar}="$(printf '%s\\n' "$posix_info" | sed -n '2p')"`, `  ${countVar}="$(printf '%s\\n' "$posix_info" | sed -n '3p')"`, `  rewrite_posix_all_shares "${name}" "$${namesVar}" "$${pathsVar}" "$PROJECT/docker-compose.yml"`);
-    }
-    if (dsmUserParam) {
-        const name = dsmUserParam.name;
-        const rawUserVar = "D54_RAW_USER_" + name;
-        // Like the Shared Folder gate: on UPGRADE the submitted user only counts when
-        // CHANGE_<name> is ticked, because the control is not reliably blank.
-        lines.push(`  if [ "$STATUS" = "UPGRADE" ] && upgrade_change_enabled "\${CHANGE_${name}:-}"; then`, `    if [ "\${${name}+x}" = x ] && [ -n "\${${name}}" ]; then`, `      ${rawUserVar}="\${${name}}"`, "    else", `      die "missing required dsm user parameter ${name}"`, "    fi", '  elif [ "$STATUS" = "UPGRADE" ] && [ -f "$CANONICAL_ENV" ] && [ ! -L "$CANONICAL_ENV" ] && ' +
-            `${rawUserVar}="$(read_env_value "$CANONICAL_ENV" "${name}")"; then`, "    :", `  elif [ "\${${name}+x}" = x ]; then`, `    ${rawUserVar}="\${${name}}"`, "  else", `    die "missing required dsm user parameter ${name}"`, "  fi", `  resolved_user_info="$(resolve_dsm_user "$${rawUserVar}")"`, "  set -- $resolved_user_info", `  ${name}_UID="$1"`, `  ${name}_GID="$2"`, "  shift 2 || true", `  ${name}_GROUPS="$*"`, `  rewrite_group_add "${name}" "$${name}_GROUPS" "$PROJECT/docker-compose.yml"`);
-    }
-    lines.push('  append_env "SYNOPKG_PKGVAR" "$PLATFORM_PKGVAR"', '  append_env "SYNO_APP_SECRETS_DIR" "$PLATFORM_SECRETS"');
-    for (const { name, valueVar, type } of valueVars) {
-        lines.push(`  append_env "${name}" "$${valueVar}" "${type}"`);
-    }
-    for (const { name, pathVar } of shareVars) {
-        lines.push(`  append_env "${name}" "$${pathVar}" "string"`);
-    }
-    for (const { name, namesVar, countVar } of posixVars) {
-        lines.push(`  append_env "${name}" "$${namesVar}" "string"`, `  append_env "${name}_COUNT" "$${countVar}" "string"`);
-    }
-    if (dsmUserParam) {
-        const name = dsmUserParam.name;
-        const rawUserVar = "D54_RAW_USER_" + name;
-        lines.push(`  append_env "${name}" "$${rawUserVar}" "string"`, `  append_env "${name}_UID" "$${name}_UID" "string"`, `  append_env "${name}_GID" "$${name}_GID" "string"`, `  idx=1`, `  for g in $${name}_GROUPS; do`, `    append_env "${name}_GROUP_\${idx}" "$g" "string"`, `    idx=$((idx + 1))`, `  done`);
-    }
-    lines.push("  } > \"$tmp\"", "  mv \"$tmp\" \"$RUNTIME_ENV\"", "  trap - EXIT HUP INT TERM", "  [ ! -L \"$RUNTIME_ENV\" ] || die \"runtime file became a symlink\"", "  [ \"$(stat -c %a \"$RUNTIME_ENV\")\" = \"600\" ] || die \"runtime env mode is not 0600\"", "exit 0");
-    return lines.join("\n") + "\n";
-}
-function renderDynamicCanonicalMirror(headless = false) {
-    const lines = [
-        "#!/bin/sh",
-        "set -eu",
-        "umask 077",
-        "# D3 post-worker mirror; the runtime .env is the only source of truth here.",
-        "die() { echo \"dynamic route canonical mirror failed: $1\" >&2; exit 1; }",
-        'PKGVAR="${SYNOPKG_PKGVAR:?}"',
-        'PKGHOME="${SYNOPKG_PKGHOME:?}"',
-        'PKGDEST="${SYNOPKG_PKGDEST:?}"',
-        'PROJECT="${PKGDEST}/compose"',
-        'RUNTIME_ENV="${PROJECT}/.env"',
-        'CANONICAL_ENV="${PKGVAR}/.env"',
-        'SECRETS="${PKGHOME}/secrets"',
-        'mkdir -p "$PKGVAR"',
-        '[ -d "$PKGVAR" ] || die "PKGVAR is not a directory"',
-        'if [ -L "$SECRETS" ]; then die "secret root is a symlink"; fi',
-        'mkdir -p "$SECRETS"',
-        '[ -d "$SECRETS" ] || die "secret root is not a directory"',
-        'chmod 700 "$SECRETS"',
-        '[ "$(stat -c %a "$SECRETS")" = "700" ] || die "secret root mode is not 0700"',
-        '[ -d "$PROJECT" ] || die "project directory is missing"',
-        '[ ! -L "$PROJECT" ] || die "project directory is a symlink"',
-        '[ ! -L "$RUNTIME_ENV" ] || die "runtime file is a symlink"',
-        '[ -f "$RUNTIME_ENV" ] || die "runtime file is not a regular file"',
-        '[ ! -L "$CANONICAL_ENV" ] || die "canonical file is a symlink"',
-        'if [ -e "$CANONICAL_ENV" ] && [ ! -f "$CANONICAL_ENV" ]; then die "canonical path is not a regular file"; fi',
-        'tmp="$(mktemp "$PKGVAR/.env.tmp.XXXXXX")"',
-        'chmod 600 "$tmp"',
-        '[ "$(stat -c %a "$tmp")" = "600" ] || die "temporary env mode is not 0600"',
-        'trap \'rm -f "$tmp"\' EXIT HUP INT TERM',
-        'cp "$RUNTIME_ENV" "$tmp"',
-        'chmod 600 "$tmp"',
-        'mv "$tmp" "$CANONICAL_ENV"',
-        'trap - EXIT HUP INT TERM',
-        '[ ! -L "$CANONICAL_ENV" ] || die "canonical file became a symlink"',
-        '[ "$(stat -c %a "$CANONICAL_ENV")" = "600" ] || die "canonical env mode is not 0600"',
-    ];
-    if (headless) {
-        lines.push('MARKER="${PKGVAR}/.docker-project-managed"', '[ ! -L "$MARKER" ] || die "docker-project marker is a symlink"', 'marker_tmp="$(mktemp "$PKGVAR/.docker-project-managed.tmp.XXXXXX")"', 'printf \'%s\\n\' managed > "$marker_tmp"', 'chmod 600 "$marker_tmp"', 'mv "$marker_tmp" "$MARKER"');
-    }
-    lines.push("exit 0");
-    return lines.join("\n") + "\n";
-}
-function shellQuote(value) {
-    return "'" + value.replace(/'/g, "'\\''") + "'";
-}
-function renderManagedScript(name, contract, isResourceWorker = false, resourceWorkerAdminport, isDynamicRoute = false, isHeadlessRoute = false) {
-    if (isResourceWorker) {
-        if (name === "start-stop-status") {
-            return renderResourceWorkerStartStopStatus(String(contract.package), resourceWorkerAdminport, isHeadlessRoute);
-        }
-        if (isDynamicRoute && name === "preinst") {
-            return renderDynamicPreinstMaterializer(contract);
-        }
-        if (isDynamicRoute && (name === "postinst" || name === "postupgrade")) {
-            return renderDynamicCanonicalMirror(isHeadlessRoute);
-        }
-        if (isHeadlessRoute && (name === "postinst" || name === "postupgrade")) {
-            return renderHeadlessResourceMarker();
-        }
-        if (name === "postuninst") {
-            const projectRoot = isDynamicRoute ? 'PROJECT="${SYNOPKG_PKGDEST:-}/compose"\n' : "";
-            const deleteRoots = [
-                { variable: "PKGVAR", area: "appdata" },
-                { variable: "PKGHOME", area: "apphome" },
-                ...(isDynamicRoute ? [{ variable: "PROJECT", area: "appstore" }] : []),
-            ];
-            return `#!/bin/sh
-set -eu
-PKGVAR="\${SYNOPKG_PKGVAR:-}"
-PKGHOME="\${SYNOPKG_PKGHOME:-}"
-${projectRoot}${renderDeleteAppDataBlock(String(contract.package), deleteRoots)}exit 0
-`;
-        }
-        return `#!/bin/sh\nexit 0\n`;
-    }
-    throw new Error("Unsupported container route");
-}
-async function createDeterministicSpk(stagingDir, outputPath) {
-    const payloadDir = join(stagingDir, "package");
-    if (existsSync(payloadDir) && statSync(payloadDir).isDirectory()) {
-        await createReproducibleTar(payloadDir, join(stagingDir, "package.tgz"), { gzip: true });
-        rmSync(payloadDir, { recursive: true, force: true });
-    }
-    await createReproducibleTar(stagingDir, outputPath);
+const INSTALL_UIFILE = "install_uifile", UPGRADE_UIFILE = "upgrade_uifile", UNINSTALL_UIFILE = "uninstall_uifile";
+/** Legacy project detection supplies a migration error, never a second builder. */
+export async function buildSpk(_options) {
+    return { ok: false, errors: ["COMPOSE_LEGACY_MANIFEST_REMOVED"] };
 }
 export function walkFiles(root, prefix = "") {
     const files = [];