electron-builder 27.0.0-alpha.0 → 27.0.0-alpha.10

package/dist/cli/migrate-schema.js

@@ -1,11 +1,116 @@
 import { createRequire } from "node:module";
-import { log } from "builder-util";
+import { AZURE_KNOWN_FIELDS, ELECTRON_DOWNLOAD_DROPPED, formatLegacyOptionMessage, MAC_SIGN_FIELDS, MAC_SIGN_REMOVED_FIELDS, MAC_UNIVERSAL_FIELDS, NSIS_CONFIG_KEYS, RESOLVED_LEGACY_CONFIG_OPTIONS, } from "app-builder-lib/internal";
+import { log, orNullIfFileNotExist } from "builder-util";
 import { promises as fs } from "fs";
 import * as path from "path";
+import { loadTypeScript, migrateProgrammaticSource } from "./migrate-schema-programmatic.js";
 const _require = createRequire(import.meta.url);
 // ─── Pure migration logic ─────────────────────────────────────────────────────
-// Azure Trusted Signing fields that are typed in v27
-const AZURE_KNOWN_FIELDS = new Set(["type", "endpoint", "codeSigningAccountName", "certificateProfileName", "publisherName", "fileDigest", "timestampRfc3161", "timestampDigest"]);
+// The v26 -> v27 key mapping is owned by app-builder-lib so the runtime guard
+// (`checkLegacyConfiguration`) and this migrator cannot drift apart. Re-exported here because these
+// names are part of this module's existing public surface.
+export { AZURE_KNOWN_FIELDS, ELECTRON_DOWNLOAD_DROPPED, MAC_SIGN_FIELDS, MAC_SIGN_REMOVED_FIELDS, MAC_UNIVERSAL_FIELDS } from "app-builder-lib/internal";
+// Advisory surfaced (informational only — never rewrites the config) when a project builds an nsis-web target. As of v27,
+// electron-updater rejects web-installer updates unless disableWebInstaller is false (v27+ nsis-web installs opt in automatically).
+export const NSIS_WEB_ADVISORY = "nsis-web target detected. In v27, electron-updater rejects web-installer updates (ERR_UPDATER_WEB_INSTALLER_DISABLED) unless autoUpdater.disableWebInstaller is false; " +
+    "installs made by a v27+ nsis-web installer opt in automatically, so set autoUpdater.disableWebInstaller = false in your main process (a runtime setting, not a build-config key) " +
+    "for installs made by an older installer or when switching from nsis to nsis-web. " +
+    "The nsis-web installer also verifies a --package-file package, and a package downloaded from the URL derived from the publish configuration (no nsisWeb.appPackageUrl), against its built-in hashes; " +
+    "set nsisWeb.allowUnverifiedAppPackage: true only if one installer is used with packages of other builds. " +
+    "See https://www.electron.build/docs/migration/v27-breaking-changes#disablewebinstaller-defaults-to-true";
+// Advisory surfaced when nsis/nsisWeb installs per-machine. v27 sets isAdminRightsRequired in the update info of per-machine builds, so
+// electron-updater starts those updates with elevate.exe and skips them in the automatic install at launch.
+export const NSIS_PER_MACHINE_UPDATE_ADVISORY = "nsis/nsisWeb perMachine: true detected. In v27, electron-updater starts per-machine updates with elevate.exe directly and does not install them automatically at launch " +
+    'with autoInstallEvent "onNextLaunch" (call autoUpdater.installPendingUpdateIfAvailable()). ' +
+    "See https://www.electron.build/docs/migration/v27-breaking-changes#nsis-per-machine-builds-set-isadminrightsrequired";
+// Advisory surfaced when a custom win.sign.sign hook has no publisherName. v27 fails such a build when it writes app-update.yml.
+export const WIN_SIGN_HOOK_PUBLISHER_NAME_ADVISORY = "win.sign.sign (custom signing hook) without win.sign.publisherName detected. In v27, a signed build that writes app-update.yml " +
+    "(an nsis, nsis-web or electronUpdaterAware appx target with a publish configuration, including one inferred from a GitHub repository) fails with InvalidConfigurationError " +
+    "because electron-builder cannot tell which certificate the hook signs with (a certificate in the config or from WIN_CSC_LINK / CSC_LINK doesn't supply the publisher name of a hook). " +
+    "Set win.sign.publisherName to the subject of the certificate your hook signs with, or win.verifyUpdateCodeSignature: false only if your updates are not Authenticode-signed. " +
+    "See https://www.electron.build/docs/migration/v27-breaking-changes#windows-publishername-is-validated-against-the-signing-certificate";
+// Advisory surfaced when a mac/mas/masDev config does not name its own entitlements file. v27 stopped granting
+// allow-unsigned-executable-memory and disable-library-validation in the bundled default, which only fails at runtime.
+export const MAC_ENTITLEMENTS_ADVISORY = "In v27 the bundled default macOS entitlements grant only com.apple.security.cs.allow-jit (allow-unsigned-executable-memory and disable-library-validation are no longer granted). " +
+    "If you rely on the default (no mac.sign.entitlements and no build/entitlements.mac.plist) and your app loads native modules, frameworks, or plugins signed by another Team ID (or unsigned), " +
+    "add those entitlements back in build/entitlements.mac.plist. See https://www.electron.build/docs/migration/v27-breaking-changes#macos-default-entitlements-tightened";
+// Advisory surfaced when a generic publish url carries a query string (typically a token). v27 electron-updater sends the feed
+// query and credential headers only to downloads on the feed's origin.
+export const FEED_QUERY_ADVISORY = "generic publish url with a query string detected. In v27, electron-updater sends the feed url's query string, and the credential headers from requestHeaders / addAuthHeader, " +
+    "only to downloads on the feed's origin (scheme, host and port); a download url in latest*.yml on another origin is requested without them. " +
+    "If those downloads need these credentials, serve the update files from the feed origin or use pre-signed URLs. " +
+    "See https://www.electron.build/docs/migration/v27-breaking-changes#update-credentials-stay-on-the-feeds-origin";
+/**
+ * macOS signing/universal fields that v26 accepted as `null` (meaning "unset") but whose v27 type has no `null`
+ * branch, so a moved `null` would fail validation. They are dropped instead of moved. `identity: null` is not in
+ * this list — it means "skip signing" and `sign.identity` still accepts it.
+ */
+export const MAC_NULL_MEANS_UNSET_FIELDS = new Set(["type", "provisioningProfile", "binaries", "signIgnore", "singleArchFiles", "x64ArchFiles"]);
+/** Platform keys that accepted a platform-level `asarUnpack` in v26. */
+export const ASAR_PLATFORM_KEYS = ["mac", "mas", "masDev", "win", "linux"];
+/** v26 `snap` options that the v27 `snapcraft.core24` shape does not accept (core24 uses the snapcraft CLI directly). */
+export const SNAP_CORE24_UNSUPPORTED = ["allowNativeWayland", "useTemplateApp"];
+/** A target name resolved like the build does: an ":<arch>" suffix is dropped and the name is lowercased ("RPM:x64" → "rpm"). */
+export function normalizeTargetName(target) {
+    const suffixPos = target.lastIndexOf(":");
+    return (suffixPos > 0 ? target.substring(0, suffixPos) : target).toLowerCase();
+}
+/** True when `target` (a string such as "deb" or "deb:arm64", a `{ target }` object, or an array of either) selects one of `names`. */
+function hasTarget(target, names) {
+    if (target == null) {
+        return false;
+    }
+    if (typeof target === "string") {
+        return names.includes(normalizeTargetName(target));
+    }
+    if (Array.isArray(target)) {
+        return target.some(it => hasTarget(it, names));
+    }
+    if (typeof target === "object") {
+        return hasTarget(target.target, names);
+    }
+    return false;
+}
+/** True when the build config selects one of `names` (via `<platform>.target` or the global target). */
+function detectTarget(config, platform, names) {
+    return hasTarget(config[platform]?.target, names) || hasTarget(config.target, names);
+}
+/**
+ * True when a custom `win.sign.sign` hook signs without `publisherName` and update signature verification is on (a certificate
+ * in the config doesn't matter: a hook always needs publisherName). Evaluated on the migrated config, so a v26
+ * `win.signtoolOptions.sign` counts too.
+ */
+function detectSignHookWithoutPublisherName(config) {
+    const win = config.win;
+    const sign = isPlainObject(win) ? win.sign : null;
+    // a function-valued hook cannot occur here: migrateConfig works on a JSON copy of the config
+    return isPlainObject(sign) && typeof sign.sign === "string" && sign.publisherName === undefined && win.verifyUpdateCodeSignature !== false;
+}
+/**
+ * True when a mac/mas/masDev section signs with electron-builder's defaults without naming its own entitlements
+ * file. A custom signer (string/function `sign`) or `sign.identity: null` (skip signing) bypasses the defaults.
+ */
+function detectDefaultMacEntitlements(config) {
+    return ["mac", "mas", "masDev"].some(p => {
+        const platform = config[p];
+        if (!isPlainObject(platform)) {
+            return false;
+        }
+        const sign = platform.sign;
+        if (typeof sign === "string" || typeof sign === "function") {
+            return false;
+        }
+        return !(isPlainObject(sign) && (sign.entitlements != null || sign.identity === null));
+    });
+}
+/** True when a root or platform/target-level `publish` (walked like step 7) has a generic provider whose url has a query string. */
+function detectGenericFeedQuery(config) {
+    return [config, ...Object.values(config)].some(section => isPlainObject(section) &&
+        (Array.isArray(section.publish) ? section.publish : [section.publish]).some((entry) => isPlainObject(entry) && entry.provider === "generic" && typeof entry.url === "string" && entry.url.includes("?")));
+}
+function isPlainObject(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
 /**
  * Applies all v26→v27 config transformations to a parsed config object.
  * Pure function — no I/O, safe to call in tests.
@@ -14,6 +119,7 @@ export function migrateConfig(raw) {
     const c = JSON.parse(JSON.stringify(raw));
     const changes = [];
     const warnings = [];
+    const advisories = [];
     // ── 1. electronCompile ────────────────────────────────────────────────────
     if ("electronCompile" in c) {
         delete c.electronCompile;
@@ -26,6 +132,32 @@ export function migrateConfig(raw) {
             changes.push({ key, description: `removed ${key} (Electron is the only supported framework in v27)` });
         }
     }
+    // ── 2b. disableDefaultIgnoredFiles removed (root + platform configs) ──────
+    // mas/masDev are MacConfiguration-derived, so they accept the (now-removed) key too.
+    for (const obj of [c, c.mac, c.mas, c.masDev, c.win, c.linux]) {
+        if (obj != null && typeof obj === "object" && "disableDefaultIgnoredFiles" in obj) {
+            delete obj.disableDefaultIgnoredFiles;
+            changes.push({
+                key: "disableDefaultIgnoredFiles",
+                description: "removed disableDefaultIgnoredFiles (in v27, include a default-excluded file via an explicit `files` glob, e.g. `**/*.obj`)",
+            });
+        }
+    }
+    // ── 2c. linux.syncDesktopName removed (always-on in v27) ──────────────────
+    // The flag is gone from the type; the behaviour it gated (deriving the installed .desktop filename
+    // from desktopName) is now always on. Leaving the key would fail v27 schema validation (noExtraProps).
+    if (c.linux != null && typeof c.linux === "object" && "syncDesktopName" in c.linux) {
+        const wasDisabled = c.linux.syncDesktopName === false;
+        delete c.linux.syncDesktopName;
+        changes.push({
+            key: "linux.syncDesktopName",
+            description: "removed linux.syncDesktopName (the installed .desktop filename is always synced from desktopName in v27)",
+        });
+        if (wasDisabled) {
+            warnings.push("linux.syncDesktopName: false disabled desktop-name syncing in v26. In v27 the installed .desktop filename is always derived from `desktopName` " +
+                "(falling back to executableName). If you relied on the old filename, set `desktopName` explicitly to control it.");
+        }
+    }
     // ── 3. npmSkipBuildFromSource → buildDependenciesFromSource ───────────────
     if ("npmSkipBuildFromSource" in c) {
         // will be picked up by the nativeModules step below
@@ -47,11 +179,20 @@ export function migrateConfig(raw) {
             }
         }
         if ("nativeRebuilder" in c) {
-            sub.rebuildMode = c.nativeRebuilder;
+            if (c.nativeRebuilder === "legacy") {
+                // v27 dropped the app-builder binary rebuilder; rebuildMode only selects @electron/rebuild's mode.
+                warnings.push('nativeRebuilder: "legacy" (the app-builder binary rebuilder) was removed in v27 — native modules are always rebuilt with @electron/rebuild. ' +
+                    'The value was dropped, so the default nativeModules.rebuildMode ("sequential") applies.');
+            }
+            else {
+                sub.rebuildMode = c.nativeRebuilder;
+            }
             delete c.nativeRebuilder;
             changes.push({ key: "nativeRebuilder", description: "renamed nativeRebuilder → nativeModules.rebuildMode" });
         }
-        c.nativeModules = sub;
+        if (Object.keys(sub).length > 0 || c.nativeModules != null) {
+            c.nativeModules = sub;
+        }
     }
     // ── 5. Legacy asar keys → asarUnpack ─────────────────────────────────────
     // Hyphenated root-level variants
@@ -83,12 +224,12 @@ export function migrateConfig(raw) {
     }
     // ── 7. GithubOptions.vPrefixedTagName → tagNamePrefix ─────────────────────
     if (c.publish != null) {
-        migratePublishEntries(c, "publish", changes);
+        migratePublishEntries(c, "publish", changes, warnings);
     }
-    // Also handle publish nested inside mac/win/linux
-    for (const platform of ["mac", "win", "linux"]) {
-        if (c[platform]?.publish != null) {
-            migratePublishEntries(c[platform], "publish", changes);
+    // Also handle publish nested inside any platform/target section (mac, win, nsis, dmg, snap, …)
+    for (const value of Object.values(c)) {
+        if (isPlainObject(value) && value.publish != null) {
+            migratePublishEntries(value, "publish", changes, warnings);
         }
     }
     // ── 8. snap → snapcraft restructuring ─────────────────────────────────────
@@ -114,10 +255,40 @@ export function migrateConfig(raw) {
         delete sq.noMsi;
         changes.push({ key: "squirrelWindows.noMsi", description: "replaced squirrelWindows.noMsi → squirrelWindows.msi (inverted boolean)" });
     }
+    // ── 10b. squirrelWindows.customSquirrelVendorDir removed (not auto-migrated) ──
+    // The v27 replacement (a toolsets.squirrel ToolsetCustom bundle) needs a different directory layout, so the
+    // key is left in place: the build then fails with a targeted message instead of silently switching the
+    // vendored Squirrel binaries back to the default bundle.
+    if (isPlainObject(c.squirrelWindows) && "customSquirrelVendorDir" in c.squirrelWindows) {
+        warnings.push("squirrelWindows.customSquirrelVendorDir was removed in v27 and cannot be migrated automatically. " +
+            'Supply the custom bundle via toolsets.squirrel: { url: "file:///abs/path" } — the bundle must contain an electron-winstaller/vendor/ subtree ' +
+            "(customSquirrelVendorDir pointed at the vendor files directly) — or remove the key to use the default Squirrel bundle.");
+    }
     // ── 11. asar consolidation ───────────────────────────────────────────────
     // Move root-level asarUnpack / disableSanityCheckAsar / disableAsarIntegrity
-    // into the asar object. Skip entirely when asar === false (all would be no-ops).
-    if (c.asar !== false) {
+    // into the asar object. In v26 these applied to every platform independently of `asar`; in v27 they live
+    // inside it, and a platform-level `asar` replaces the root one wholesale — so capture them first for step 11b.
+    const rootAsarValue = c.asar;
+    const rootFlatAsar = {};
+    if ("asarUnpack" in c) {
+        rootFlatAsar.unpack = c.asarUnpack;
+    }
+    if ("disableSanityCheckAsar" in c) {
+        rootFlatAsar.disableSanityCheck = c.disableSanityCheckAsar;
+    }
+    if ("disableAsarIntegrity" in c) {
+        rootFlatAsar.disableIntegrity = c.disableAsarIntegrity;
+    }
+    if (c.asar === false) {
+        // No effect on the root build; step 11b still carries them into any platform that re-enables asar.
+        for (const key of ["asarUnpack", "disableSanityCheckAsar", "disableAsarIntegrity"]) {
+            if (key in c) {
+                delete c[key];
+                changes.push({ key, description: `removed ${key} (no effect with asar: false)` });
+            }
+        }
+    }
+    else {
         const asarSub = typeof c.asar === "object" && c.asar != null ? { ...c.asar } : {};
         if ("asarUnpack" in c) {
             asarSub.unpack = mergeAsarUnpack(asarSub.unpack, c.asarUnpack);
@@ -137,35 +308,460 @@ export function migrateConfig(raw) {
         if (c.asar === true) {
             if (Object.keys(asarSub).length > 0) {
                 c.asar = asarSub;
+                changes.push({ key: "asar", description: `replaced asar: true with an asar object carrying ${Object.keys(asarSub).join(", ")}` });
             }
             else {
                 delete c.asar;
+                changes.push({ key: "asar", description: "removed redundant asar: true (asar is enabled by default; the explicit `true` is not needed)" });
             }
-            changes.push({ key: "asar", description: "replaced asar: true with asar object (true is no longer a valid value)" });
         }
         else if (Object.keys(asarSub).length > 0) {
             c.asar = asarSub;
         }
     }
-    // ── 12. azureSignOptions: index-signature extra keys → additionalMetadata ─
-    if (c.win?.azureSignOptions != null) {
-        const azure = c.win.azureSignOptions;
-        const extra = {};
-        for (const [k, v] of Object.entries(azure)) {
-            if (!AZURE_KNOWN_FIELDS.has(k) && typeof v === "string") {
-                extra[k] = v;
-                delete azure[k];
+    // ── 11b. platform-level asar ──────────────────────────────────────────────
+    for (const platform of ASAR_PLATFORM_KEYS) {
+        if (isPlainObject(c[platform])) {
+            migratePlatformAsar(c, platform, rootAsarValue, rootFlatAsar, changes);
+        }
+    }
+    // ── 12. win.sign unification ───────────────────────────────────────────────
+    // win.signtoolOptions → win.sign: { type: "signtool", … }
+    // win.azureSignOptions → win.sign: { type: "azure", … }  (extra keys → additionalMetadata)
+    // win.signAndEditExecutable / win.signExecutable removed
+    if (c.win != null && typeof c.win === "object") {
+        const win = c.win;
+        // Remove defunct flags — signAndEditExecutable/signExecutable no longer exist in v27. Either one set to
+        // false skipped ALL signing in v26, so both map to win.sign: false (signAndEditExecutable also skipped
+        // resource editing, which always runs in v27 — that part has no equivalent).
+        const signingDisabled = win.signExecutable === false || win.signAndEditExecutable === false;
+        if ("signAndEditExecutable" in win) {
+            const val = win.signAndEditExecutable;
+            delete win.signAndEditExecutable;
+            if (val === false) {
+                warnings.push("win.signAndEditExecutable: false was used to skip both resource editing and signing. " +
+                    "In v27, resource editing always runs; signing is still skipped via win.sign: false. " +
+                    "There is no v27 equivalent that also skips resource editing — apply resources manually if needed.");
+            }
+            changes.push({ key: "win.signAndEditExecutable", description: "removed win.signAndEditExecutable (resource editing always runs in v27)" });
+        }
+        if ("signExecutable" in win) {
+            delete win.signExecutable;
+            changes.push({ key: "win.signExecutable", description: "removed win.signExecutable (signing is enabled by default when credentials are available)" });
+        }
+        if (signingDisabled && win.sign == null) {
+            win.sign = false;
+            changes.push({ key: "win.sign", description: "set win.sign: false (v26 signExecutable/signAndEditExecutable: false disabled signing; resource editing still runs)" });
+        }
+        if (win.sign === false && (win.azureSignOptions != null || win.signtoolOptions != null)) {
+            // Signing was switched off, so the legacy options never applied. Only their key names are reported —
+            // the values can hold certificate passwords.
+            const dropped = ["signtoolOptions", "azureSignOptions"].filter(k => win[k] != null);
+            for (const k of dropped) {
+                delete win[k];
+                changes.push({ key: `win.${k}`, description: `removed win.${k} (signing is disabled with win.sign: false)` });
+            }
+            warnings.push(`win.sign is false (signing disabled), so [${dropped.map(k => `win.${k}`).join(", ")}] had no effect and ${dropped.length === 1 ? "was" : "were"} removed. ` +
+                'To sign in v27, replace win.sign: false with win.sign: { type: "signtool" | "azure", … } carrying those options.');
+        }
+        const hasAzure = win.azureSignOptions != null;
+        const hasSigntool = win.signtoolOptions != null;
+        if (hasAzure || hasSigntool) {
+            const signAlreadySet = "sign" in win && win.sign !== null && win.sign !== undefined;
+            if (signAlreadySet) {
+                warnings.push("win.sign is already set alongside " +
+                    (hasAzure ? "win.azureSignOptions" : "win.signtoolOptions") +
+                    ". Remove the legacy key manually after verifying win.sign is correct.");
+            }
+            else {
+                if (hasAzure && hasSigntool) {
+                    warnings.push("Both win.azureSignOptions and win.signtoolOptions are set. " +
+                        "win.signtoolOptions will be dropped and win.azureSignOptions will be migrated to win.sign: { type: 'azure', … } (Azure took priority in v26). " +
+                        "Verify the migrated win.sign block is correct for your project.");
+                    delete win.signtoolOptions;
+                }
+                if (hasAzure) {
+                    const azure = { ...win.azureSignOptions };
+                    delete win.azureSignOptions;
+                    // Move extra (untyped) keys into additionalMetadata
+                    const extra = {};
+                    for (const [k, v] of Object.entries(azure)) {
+                        if (!AZURE_KNOWN_FIELDS.has(k) && typeof v === "string") {
+                            extra[k] = v;
+                            delete azure[k];
+                        }
+                    }
+                    if (Object.keys(extra).length > 0) {
+                        azure.additionalMetadata = { ...(azure.additionalMetadata ?? {}), ...extra };
+                        changes.push({
+                            key: "win.azureSignOptions",
+                            description: `moved extra keys [${Object.keys(extra).join(", ")}] into win.sign.additionalMetadata`,
+                        });
+                    }
+                    win.sign = { ...azure, type: "azure" };
+                    changes.push({ key: "win.azureSignOptions", description: 'moved win.azureSignOptions → win.sign: { type: "azure", … }' });
+                }
+                else {
+                    const signtool = { ...win.signtoolOptions };
+                    delete win.signtoolOptions;
+                    win.sign = { ...signtool, type: "signtool" };
+                    changes.push({ key: "win.signtoolOptions", description: 'moved win.signtoolOptions → win.sign: { type: "signtool", … }' });
+                }
+            }
+        }
+    }
+    // ── 13. mac/mas/masDev signing + universal consolidation ──────────────────
+    // Signing fields (incl. identity) move into `sign`; mergeASARs/singleArchFiles/x64ArchFiles into `universal`.
+    for (const platform of ["mac", "mas", "masDev"]) {
+        if (c[platform] != null && typeof c[platform] === "object") {
+            migrateMacSigning(c[platform], platform, changes, warnings);
+            migrateMacUniversal(c[platform], platform, changes);
+        }
+    }
+    // ── 14. electronDownload → electronGet ────────────────────────────────────
+    if ("electronDownload" in c) {
+        migrateElectronDownload(c, "electronDownload", changes, warnings);
+    }
+    else if (isPlainObject(c.electronGet) && Object.keys(c.electronGet).some(isLegacyElectronDownloadKey)) {
+        // A hand-renamed `electronGet` that still carries the v26 shape.
+        migrateElectronDownload(c, "electronGet", changes, warnings);
+    }
+    // ── 15. toolsets ──────────────────────────────────────────────────────────
+    if (isPlainObject(c.toolsets)) {
+        migrateToolsets(c.toolsets, changes);
+    }
+    // Advisories (not config changes): v27 runtime defaults and behavior changes that a config rewrite cannot address.
+    if (detectTarget(c, "win", ["nsis-web"])) {
+        advisories.push(NSIS_WEB_ADVISORY);
+    }
+    if (detectDefaultMacEntitlements(c)) {
+        advisories.push(MAC_ENTITLEMENTS_ADVISORY);
+    }
+    if (c.nsis?.perMachine === true || c.nsisWeb?.perMachine === true) {
+        advisories.push(NSIS_PER_MACHINE_UPDATE_ADVISORY);
+    }
+    if (detectSignHookWithoutPublisherName(c)) {
+        advisories.push(WIN_SIGN_HOOK_PUBLISHER_NAME_ADVISORY);
+    }
+    if (detectGenericFeedQuery(c)) {
+        advisories.push(FEED_QUERY_ADVISORY);
+    }
+    // ── nsis/nsisWeb/portable customNsisBinary / customNsisResources removed ──
+    // Kept keys are reported only after `modified` is computed: a key that is merely kept must not re-serialize the file
+    // (dropping YAML/JSON5 comments) when nothing else changed. The build then fails with the same targeted message.
+    const keptKeyWarnings = [];
+    migrateCustomNsis(c, changes, warnings, keptKeyWarnings);
+    const modified = changes.length > 0 || warnings.length > 0;
+    warnings.push(...keptKeyWarnings);
+    return { migrated: c, changes, warnings, advisories, modified };
+}
+/** The build-time guard's message for a removed key (`nsis.customNsisBinary`), reused for the keys migrate-schema leaves in place. */
+export function legacyKeyMessage(fullPath) {
+    const option = RESOLVED_LEGACY_CONFIG_OPTIONS.find(o => o.fullPath === fullPath);
+    if (option == null) {
+        throw new Error(`no legacy config option for ${fullPath}`);
+    }
+    return formatLegacyOptionMessage(option);
+}
+/** Warning for a `portable.customNsisBinary.debugLogging` that migrate-schema drops. */
+export const PORTABLE_DEBUG_LOGGING_DROPPED = "portable.customNsisBinary.debugLogging was dropped: it never had an effect on portable targets (the portable template does not enable NSIS logging), and v27 has no portable equivalent.";
+/**
+ * `customNsisBinary.debugLogging` moves to `<section>.installerDebugLogging` (nsis / nsisWeb; dropped for portable), and an
+ * emptied or null `customNsisBinary` / `customNsisResources` is removed. A custom bundle (url / checksum / version, or the resources
+ * bundle) is never converted to `toolsets.nsis`: the bundle layout differs (it must carry the NSIS plugins), so the key is kept and reported.
+ */
+function migrateCustomNsis(c, changes, warnings, keptKeyWarnings) {
+    for (const section of NSIS_CONFIG_KEYS) {
+        const options = c[section];
+        if (!isPlainObject(options)) {
+            continue;
+        }
+        const binaryPath = `${section}.customNsisBinary`;
+        const binary = options.customNsisBinary;
+        if (binary === null) {
+            delete options.customNsisBinary;
+            changes.push({ key: binaryPath, description: `removed ${binaryPath}: null (the key was removed in v27)` });
+        }
+        else if (isPlainObject(binary)) {
+            if ("debugLogging" in binary) {
+                const debugLogging = binary.debugLogging;
+                delete binary.debugLogging;
+                if (section === "portable") {
+                    if (debugLogging != null) {
+                        warnings.push(PORTABLE_DEBUG_LOGGING_DROPPED);
+                    }
+                    changes.push({ key: `${binaryPath}.debugLogging`, description: `removed ${binaryPath}.debugLogging (no effect on portable targets)` });
+                }
+                else if (debugLogging != null && !("installerDebugLogging" in options)) {
+                    options.installerDebugLogging = debugLogging;
+                    changes.push({ key: `${binaryPath}.debugLogging`, description: `moved ${binaryPath}.debugLogging → ${section}.installerDebugLogging` });
+                }
+                else {
+                    changes.push({ key: `${binaryPath}.debugLogging`, description: `removed ${binaryPath}.debugLogging` });
+                }
+            }
+            if (Object.values(binary).every(v => v == null)) {
+                delete options.customNsisBinary;
+                changes.push({ key: binaryPath, description: `removed ${binaryPath} (no custom bundle was set)` });
+            }
+            else {
+                keptKeyWarnings.push(legacyKeyMessage(binaryPath));
             }
         }
-        if (Object.keys(extra).length > 0) {
-            azure.additionalMetadata = { ...(azure.additionalMetadata ?? {}), ...extra };
+        else if (binary !== undefined) {
+            keptKeyWarnings.push(legacyKeyMessage(binaryPath));
+        }
+        const resourcesPath = `${section}.customNsisResources`;
+        if (options.customNsisResources === null) {
+            delete options.customNsisResources;
+            changes.push({ key: resourcesPath, description: `removed ${resourcesPath}: null (the key was removed in v27)` });
+        }
+        else if (options.customNsisResources !== undefined) {
+            keptKeyWarnings.push(legacyKeyMessage(resourcesPath));
+        }
+    }
+}
+/**
+ * Moves macOS signing fields from a platform config (mac/mas/masDev) into the `sign` bag and
+ * renames `signIgnore` → `sign.ignore`. In v26 `sign` was only a custom-signer (string path / module id),
+ * so a non-object `sign` cannot absorb these options — that case is warned about, not clobbered.
+ * A bare `sign: null` (v26 "no custom signer") is dropped so it does not flip to v27's "skip signing".
+ */
+function migrateMacSigning(platform, name, changes, warnings) {
+    const present = MAC_SIGN_FIELDS.filter(f => f in platform);
+    const hasSignIgnore = "signIgnore" in platform;
+    const existingSign = platform.sign;
+    const signIsCustom = typeof existingSign === "string" || typeof existingSign === "function";
+    // Removed outright, not moved: ElectronSignOptions omits these and the schema rejects them, so
+    // relocating them under `sign` would emit a config that fails validation on the next build.
+    for (const field of MAC_SIGN_REMOVED_FIELDS) {
+        if (field in platform) {
+            delete platform[field];
+            changes.push({ key: `${name}.${field}`, description: `removed ${name}.${field} (@electron/osx-sign 2.x dropped the spctl --assess step; there is no ${name}.sign.${field})` });
+        }
+    }
+    if (present.length === 0 && !hasSignIgnore) {
+        // Only thing to fix is a semantically-flipped bare null
+        if (existingSign === null) {
+            delete platform.sign;
+            changes.push({ key: `${name}.sign`, description: `removed ${name}.sign: null (v26 "no custom signer" = v27 default; sign: null now means skip signing)` });
+        }
+        return;
+    }
+    if (signIsCustom) {
+        const fields = [...present, ...(hasSignIgnore ? ["signIgnore"] : [])].join(", ");
+        warnings.push(`${name}.sign is a custom signing function/path, which cannot hold options. Move [${fields}] into an ElectronSignOptions object manually, or keep the custom signer and drop them.`);
+        return;
+    }
+    // existingSign is null/undefined or already an object → build the merged options bag
+    const signObj = existingSign != null && typeof existingSign === "object" ? { ...existingSign } : {};
+    for (const f of present) {
+        if (dropNullField(platform, f, name, changes)) {
+            continue;
+        }
+        signObj[f] = platform[f];
+        delete platform[f];
+        changes.push({ key: `${name}.${f}`, description: `moved ${name}.${f} → ${name}.sign.${f}` });
+    }
+    if (hasSignIgnore && !dropNullField(platform, "signIgnore", name, changes)) {
+        signObj.ignore = platform.signIgnore;
+        delete platform.signIgnore;
+        changes.push({ key: `${name}.signIgnore`, description: `renamed ${name}.signIgnore → ${name}.sign.ignore` });
+    }
+    if (Object.keys(signObj).length > 0 || existingSign != null) {
+        platform.sign = signObj;
+    }
+    else if (existingSign === null) {
+        // Every moved field was a dropped null — a bare `sign: null` left behind would now mean "skip signing".
+        delete platform.sign;
+        changes.push({ key: `${name}.sign`, description: `removed ${name}.sign: null (v26 "no custom signer" = v27 default; sign: null now means skip signing)` });
+    }
+}
+/** Drops a v26 `null` ("unset") for a field whose v27 type has no null branch. Returns true when dropped. */
+function dropNullField(platform, field, name, changes) {
+    if (platform[field] !== null || !MAC_NULL_MEANS_UNSET_FIELDS.has(field)) {
+        return false;
+    }
+    delete platform[field];
+    changes.push({ key: `${name}.${field}`, description: `removed ${name}.${field}: null (null meant "unset" in v26; the v27 option does not accept null)` });
+    return true;
+}
+/** Moves universal-build fields from a platform config into the `universal` bag. */
+function migrateMacUniversal(platform, name, changes) {
+    const present = MAC_UNIVERSAL_FIELDS.filter(f => f in platform);
+    if (present.length === 0) {
+        return;
+    }
+    const universalObj = platform.universal != null && typeof platform.universal === "object" ? { ...platform.universal } : {};
+    for (const f of present) {
+        if (dropNullField(platform, f, name, changes)) {
+            continue;
+        }
+        universalObj[f] = platform[f];
+        delete platform[f];
+        changes.push({ key: `${name}.${f}`, description: `moved ${name}.${f} → ${name}.universal.${f}` });
+    }
+    if (Object.keys(universalObj).length > 0 || platform.universal != null) {
+        platform.universal = universalObj;
+    }
+}
+/**
+ * Moves a platform-level `asarUnpack` into that platform's `asar` object.
+ *
+ * v26 concatenated root and platform `asarUnpack` and always applied the root `disableSanityCheckAsar` /
+ * `disableAsarIntegrity`, whatever the platform's `asar` was. v27 keeps all three inside `asar`, and a
+ * platform-level `asar` replaces the root one entirely — so a platform that overrides `asar` (or gains one
+ * here) gets the root values folded in to keep the v26 result.
+ */
+function migratePlatformAsar(c, name, rootAsarValue, rootFlatAsar, changes) {
+    const platform = c[name];
+    const hasUnpack = "asarUnpack" in platform;
+    const own = platform.asar;
+    if (own == null) {
+        // Inherits the root asar — only needs an override of its own to carry a platform asarUnpack.
+        if (!hasUnpack) {
+            return;
+        }
+        if (rootAsarValue === false) {
+            delete platform.asarUnpack;
+            changes.push({ key: `${name}.asarUnpack`, description: `removed ${name}.asarUnpack (no effect with asar: false)` });
+            return;
+        }
+        const next = isPlainObject(c.asar) ? { ...c.asar } : {};
+        next.unpack = mergeAsarUnpack(next.unpack, platform.asarUnpack);
+        platform.asar = next;
+        delete platform.asarUnpack;
+        changes.push({
+            key: `${name}.asarUnpack`,
+            description: `moved ${name}.asarUnpack → ${name}.asar.unpack (merged with the root asar options, since a platform-level asar replaces the root one)`,
+        });
+        return;
+    }
+    if (own === false) {
+        if (hasUnpack) {
+            delete platform.asarUnpack;
+            changes.push({ key: `${name}.asarUnpack`, description: `removed ${name}.asarUnpack (no effect with ${name}.asar: false)` });
+        }
+        return;
+    }
+    // own is true or an AsarOptions object: fold the v26 root-level options (and the platform asarUnpack) into it.
+    const next = isPlainObject(own) ? { ...own } : {};
+    const folded = [];
+    if (rootFlatAsar.unpack != null || hasUnpack) {
+        // v26 order: root patterns first, then the platform's own.
+        let unpack = undefined;
+        for (const it of [rootFlatAsar.unpack, next.unpack, hasUnpack ? platform.asarUnpack : undefined]) {
+            if (it != null) {
+                unpack = mergeAsarUnpack(unpack, it);
+            }
+        }
+        if (unpack !== undefined) {
+            next.unpack = unpack;
+            folded.push("unpack");
+        }
+    }
+    for (const key of ["disableSanityCheck", "disableIntegrity"]) {
+        if (key in rootFlatAsar && !(key in next)) {
+            next[key] = rootFlatAsar[key];
+            folded.push(key);
+        }
+    }
+    if (hasUnpack) {
+        delete platform.asarUnpack;
+    }
+    if (folded.length === 0) {
+        return;
+    }
+    platform.asar = next;
+    changes.push({
+        key: hasUnpack ? `${name}.asarUnpack` : `${name}.asar`,
+        description: `folded ${folded.map(k => `asar.${k}`).join(", ")} into ${name}.asar (a platform-level asar replaces the root one in v27, so the v26 root-level values are copied)`,
+    });
+}
+/** Removes `null` toolset values (rejected by the v27 schema) and remaps pins to bundles that are no longer published. */
+function migrateToolsets(toolsets, changes) {
+    for (const [key, value] of Object.entries(toolsets)) {
+        if (value === null) {
+            delete toolsets[key];
             changes.push({
-                key: "win.azureSignOptions",
-                description: `moved extra keys [${Object.keys(extra).join(", ")}] into win.azureSignOptions.additionalMetadata`,
+                key: `toolsets.${key}`,
+                description: `removed toolsets.${key}: null (v27 rejects null; unset resolves to "latest", the newest bundle — pin "0.0.0" to keep the legacy bundle v26 used)`,
             });
         }
     }
-    return { migrated: c, changes, warnings, modified: changes.length > 0 || warnings.length > 0 };
+    if (toolsets.appimage === "1.0.2") {
+        toolsets.appimage = "1.0.3";
+        changes.push({
+            key: "toolsets.appimage",
+            description: 'replaced toolsets.appimage: "1.0.2" with "1.0.3" (1.0.2 is no longer offered; 1.0.3 is the same runtime with the #9598 fix)',
+        });
+    }
+}
+/**
+ * Renames `electronDownload` → `electronGet` and reshapes it to ElectronGetOptions.
+ * `mirror` → `mirrorOptions.mirror`, `isVerifyChecksum: false` → `unsafelyDisableChecksums: true`.
+ * Fields with no v5 equivalent are dropped with a warning.
+ */
+function migrateElectronDownload(c, sourceKey, changes, warnings) {
+    const old = c[sourceKey];
+    delete c[sourceKey];
+    if (old == null || typeof old !== "object") {
+        changes.push({ key: "electronDownload", description: "renamed electronDownload → electronGet" });
+        if (old != null && c.electronGet == null) {
+            c.electronGet = old;
+        }
+        return;
+    }
+    const next = {};
+    if ("mirror" in old && old.mirror != null) {
+        next.mirrorOptions = { ...(next.mirrorOptions ?? {}), mirror: old.mirror };
+    }
+    if (old.isVerifyChecksum === false) {
+        next.unsafelyDisableChecksums = true;
+    }
+    // Carry over any already-valid ElectronGetOptions fields (mirrorOptions, unsafelyDisableChecksums, force, etc.)
+    for (const [k, v] of Object.entries(old)) {
+        if (k !== "mirror" && k !== "isVerifyChecksum" && !ELECTRON_DOWNLOAD_DROPPED.includes(k)) {
+            next[k] = v;
+        }
+    }
+    const dropped = ELECTRON_DOWNLOAD_DROPPED.filter(k => k in old);
+    if (dropped.length > 0) {
+        warnings.push(`electronGet (formerly electronDownload) dropped [${dropped.join(", ")}] — these have no equivalent in @electron/get v5. Set a mirror via electronGet.mirrorOptions if needed.`);
+    }
+    // An electronGet that already exists is the v27 intent: fold the legacy values in underneath it, never over it.
+    const existing = sourceKey === "electronDownload" && isPlainObject(c.electronGet) ? c.electronGet : null;
+    if (existing != null) {
+        const conflicts = [];
+        let mergedMirrorOptions;
+        for (const [k, v] of Object.entries(next)) {
+            if (k === "mirrorOptions" && isPlainObject(v) && isPlainObject(existing.mirrorOptions)) {
+                const own = existing.mirrorOptions;
+                conflicts.push(...Object.keys(v)
+                    .filter(m => m in own && JSON.stringify(own[m]) !== JSON.stringify(v[m]))
+                    .map(m => `mirrorOptions.${m}`));
+                mergedMirrorOptions = { ...v, ...own };
+            }
+            else if (k in existing && JSON.stringify(existing[k]) !== JSON.stringify(v)) {
+                conflicts.push(k);
+            }
+        }
+        Object.assign(next, existing, mergedMirrorOptions != null ? { mirrorOptions: mergedMirrorOptions } : {});
+        if (conflicts.length > 0) {
+            warnings.push(`Both electronDownload and electronGet set [${conflicts.join(", ")}]; kept the existing electronGet values and dropped the electronDownload ones. Verify the merged electronGet.`);
+        }
+    }
+    c.electronGet = next;
+    changes.push({
+        key: sourceKey,
+        description: sourceKey === "electronDownload"
+            ? "renamed electronDownload → electronGet (mirror → mirrorOptions.mirror; isVerifyChecksum → unsafelyDisableChecksums)"
+            : "reshaped electronGet to the v27 options (mirror → mirrorOptions.mirror; isVerifyChecksum → unsafelyDisableChecksums)",
+    });
+}
+/** Keys of the v26 `electronDownload` shape that are not valid v27 `electronGet` keys. */
+export function isLegacyElectronDownloadKey(key) {
+    return key === "mirror" || key === "isVerifyChecksum" || ELECTRON_DOWNLOAD_DROPPED.includes(key);
 }
 function mergeAsarUnpack(existing, incoming) {
     if (existing == null) {
@@ -174,27 +770,36 @@ function mergeAsarUnpack(existing, incoming) {
     const arr = (Array.isArray(existing) ? existing : [existing]).concat(Array.isArray(incoming) ? incoming : [incoming]);
     return arr.length === 1 ? arr[0] : arr;
 }
-function migratePublishEntries(parent, key, changes) {
+function migratePublishEntries(parent, key, changes, warnings) {
     const entries = Array.isArray(parent[key]) ? parent[key] : [parent[key]];
     let changed = false;
     for (const entry of entries) {
-        if (entry != null && entry.provider === "github" && "vPrefixedTagName" in entry) {
-            entry.tagNamePrefix = entry.vPrefixedTagName === false ? "" : "v";
+        if (entry == null || entry.provider !== "github") {
+            continue;
+        }
+        if ("vPrefixedTagName" in entry) {
+            // v26 githubTagPrefix(): a non-empty tagNamePrefix won; otherwise vPrefixedTagName (default true) chose "v" or "".
+            entry.tagNamePrefix = entry.tagNamePrefix ? entry.tagNamePrefix : entry.vPrefixedTagName === false ? "" : "v";
             delete entry.vPrefixedTagName;
             changed = true;
         }
-        if (entry != null && entry.provider === "gitlab" && "vPrefixedTagName" in entry) {
-            delete entry.vPrefixedTagName;
+        else if (entry.tagNamePrefix === "") {
+            // v26 ignored an empty tagNamePrefix and still tagged "v1.2.3"; v27 honors it and would tag "1.2.3".
+            entry.tagNamePrefix = "v";
             changed = true;
+            warnings.push('A GitHub publish entry set tagNamePrefix: "". v26 ignored an empty prefix and tagged releases "v<version>"; v27 honors it. ' +
+                'It was rewritten to tagNamePrefix: "v" to keep your existing tag names — set it back to "" if you want unprefixed tags from now on.');
         }
+        // GitLab keeps vPrefixedTagName in v27 — it remains in the type, scheme, and runtime
+        // (gitlabPublisher honors it) and has no tagNamePrefix equivalent, so leave it untouched.
     }
     if (changed) {
-        changes.push({ key: `${key}[].vPrefixedTagName`, description: "replaced vPrefixedTagName with tagNamePrefix on GitHub publish entries; removed from GitLab entries" });
+        changes.push({ key: `${key}[].vPrefixedTagName`, description: "replaced vPrefixedTagName with tagNamePrefix on GitHub publish entries" });
     }
 }
 // snap bases recognized by the v27 snapcraft config. "custom" uses an inline/path yaml
 // and must be moved verbatim rather than nested under a per-base sub-key.
-const SNAP_BASES = new Set(["core18", "core20", "core22", "core24", "custom"]);
+export const SNAP_BASES = new Set(["core18", "core20", "core22", "core24", "custom"]);
 /**
  * Migrates the removed flat `snap` config into the v27 `snapcraft` shape:
  *   { snapcraft: { base, [base]: { ...rest } } }
@@ -227,6 +832,15 @@ function migrateSnap(c, changes, warnings) {
         base = "core20";
         assumed = true;
     }
+    if (base === "core24") {
+        const unsupported = SNAP_CORE24_UNSUPPORTED.filter(k => k in rest);
+        for (const k of unsupported) {
+            delete rest[k];
+        }
+        if (unsupported.length > 0) {
+            warnings.push(`snap config set [${unsupported.join(", ")}], which the v27 snapcraft.core24 options do not support (core24 builds with the snapcraft CLI directly); they were dropped.`);
+        }
+    }
     snapcraft.base = base;
     snapcraft[base] = { ...(snapcraft[base] ?? {}), ...rest };
     c.snapcraft = snapcraft;
@@ -261,6 +875,8 @@ function serializeConfig(content, format, originalText) {
     const indent = indentMatch ? indentMatch[1].length : 2;
     return JSON.stringify(content, null, indent) + "\n";
 }
+/** Extensions of the `electron-builder.<ext>` files auto-detected when `--config` is omitted, in lookup order. */
+const CONFIG_FILE_EXTENSIONS = ["yml", "yaml", "json", "json5", "toml", "js", "cjs", "mjs", "ts"];
 async function findAndLoadConfig(projectDir, explicitConfigPath) {
     if (explicitConfigPath != null) {
         const abs = path.resolve(projectDir, explicitConfigPath);
@@ -288,7 +904,7 @@ async function findAndLoadConfig(projectDir, explicitConfigPath) {
         }
     }
     // Standalone config files
-    const candidates = [".yml", ".yaml", ".json", ".json5", ".toml", ".js", ".cjs", ".mjs", ".ts"].map(ext => path.join(projectDir, `electron-builder${ext}`));
+    const candidates = CONFIG_FILE_EXTENSIONS.map(ext => path.join(projectDir, `electron-builder.${ext}`));
     for (const candidate of candidates) {
         const text = await readFileSafe(candidate);
         if (text != null) {
@@ -299,6 +915,10 @@ async function findAndLoadConfig(projectDir, explicitConfigPath) {
     return null;
 }
 function parseConfig(text, format) {
+    if (format === "js") {
+        // Programmatic configs (JS/TS/MJS/CJS) can't be parsed; migrateSchema will bail with manual steps
+        return {};
+    }
     if (format === "yaml") {
         const yaml = _require("js-yaml");
         return yaml.load(text);
@@ -314,7 +934,7 @@ function parseConfig(text, format) {
     return JSON.parse(text);
 }
 async function readFileSafe(p) {
-    return fs.readFile(p, "utf8").catch(e => (e.code === "ENOENT" || e.code === "ENOTDIR" ? null : Promise.reject(e)));
+    return orNullIfFileNotExist(fs.readFile(p, "utf8"));
 }
 async function writeBackConfig(found, migrated, projectDir) {
     if (found.isPackageJson) {
@@ -359,36 +979,46 @@ export async function migrateSchema(args) {
     const dryRun = args["dry-run"] ?? false;
     const found = await findAndLoadConfig(projectDir, configPath);
     if (found == null) {
-        log.error(null, "no config found — checked package.json build key and electron-builder.{yml,yaml,json,json5,toml,js,cjs,ts}");
+        // A missing --config file was already reported by findAndLoadConfig.
+        if (configPath == null) {
+            log.error({ projectDir }, `no config found — checked the "build" key of package.json and electron-builder.{${CONFIG_FILE_EXTENSIONS.join(",")}}. ` +
+                "If your config file has another name (e.g. one you pass to `electron-builder --config`), run `electron-builder migrate-schema --config <path>`");
+        }
         process.exit(1);
     }
     const location = found.isPackageJson ? 'package.json ("build" key)' : path.relative(projectDir, found.configFile);
     log.info({ file: location }, "loaded config");
-    // Programmatic formats can't be auto-rewritten
+    // Programmatic formats (JS/TS) are rewritten surgically via an AST-located text codemod.
     if (found.format === "js") {
-        log.warn({ file: location }, "programmatic config cannot be auto-migrated; apply these changes manually:");
-        printManualSteps();
+        await migrateProgrammaticConfigFile(found, location, dryRun);
         return;
     }
     // TOML: can parse but not serialize (toml lib is read-only)
     const isToml = found.format === "toml";
     const result = migrateConfig(found.parsed);
-    const { migrated, warnings } = result;
+    const { migrated, warnings, advisories } = result;
     const changes = [...result.changes];
     if (found.rootDirectoriesMoved) {
         changes.push({ key: "directories", description: "moved package.json root-level directories → build.directories" });
     }
     const modified = result.modified || found.rootDirectoriesMoved === true;
-    if (!modified) {
-        log.info(null, "config is already up to date — no changes needed");
-        return;
-    }
     for (const change of changes) {
         log.info({ key: change.key }, change.description);
     }
     for (const warning of warnings) {
         log.warn(null, warning);
     }
+    // Advisories are informational and surface even when nothing changed; they never cause a rewrite.
+    for (const advisory of advisories) {
+        log.warn(null, advisory);
+    }
+    if (!modified) {
+        // A kept key (e.g. a customNsisBinary with a url) leaves the config unmodified but is not "up to date".
+        if (advisories.length === 0 && warnings.length === 0) {
+            log.info(null, "config is already up to date — no changes needed");
+        }
+        return;
+    }
     if (isToml) {
         log.warn({ file: location }, "TOML configs cannot be automatically rewritten; apply the changes above manually");
         return;
@@ -403,23 +1033,81 @@ export async function migrateSchema(args) {
         log.warn(null, "JSON5 was re-serialized as JSON — comments were not preserved");
     }
 }
+async function migrateProgrammaticConfigFile(found, location, dryRun) {
+    if (loadTypeScript() == null) {
+        log.warn({ file: location }, "auto-migration of programmatic configs requires the 'typescript' package, which was not found. Install it (e.g. `npm i -D typescript`) or apply these changes manually:");
+        printManualSteps();
+        return;
+    }
+    const result = migrateProgrammaticSource(found.rawText, found.configFile);
+    const printAdvisories = () => {
+        for (const advisory of result.advisories) {
+            log.warn(null, advisory);
+        }
+    };
+    if (result.status === "unsupported") {
+        log.warn({ file: location, reason: result.unsupportedReason }, "this programmatic config could not be auto-migrated; apply these changes manually:");
+        printManualSteps();
+        printAdvisories();
+        return;
+    }
+    if (result.status === "no-op") {
+        // A no-op can still carry warnings for keys that cannot be rewritten (e.g. customSquirrelVendorDir).
+        for (const warning of result.warnings) {
+            log.warn(null, warning);
+        }
+        if (result.advisories.length === 0 && result.warnings.length === 0) {
+            log.info(null, "config is already up to date — no changes needed");
+        }
+        printAdvisories();
+        return;
+    }
+    for (const change of result.changes) {
+        log.info({ key: change.key }, change.description);
+    }
+    for (const warning of result.warnings) {
+        log.warn(null, warning);
+    }
+    printAdvisories();
+    if (dryRun) {
+        log.info(null, "dry run — no files written");
+        return;
+    }
+    await fs.writeFile(found.configFile, result.code, "utf8");
+    log.info({ file: location }, "wrote migrated config");
+}
 function printManualSteps() {
     const steps = [
+        "",
         "• Remove electronCompile",
         "• Remove framework, nodeVersion, launchUiVersion",
         "• Rename npmSkipBuildFromSource → buildDependenciesFromSource",
-        "• Move buildDependenciesFromSource, nodeGypRebuild, npmRebuild, nativeRebuilder into nativeModules (rename nativeRebuilder → rebuildMode)",
-        "• Rename asar-unpack / asar-unpack-dir / asar.unpack / asar.unpackDir → asarUnpack; then move asarUnpack → asar.unpack",
+        '• Move buildDependenciesFromSource, nodeGypRebuild, npmRebuild, nativeRebuilder into nativeModules (rename nativeRebuilder → rebuildMode; drop a "legacy" value)',
+        "• Rename asar-unpack / asar-unpack-dir / asar.unpackDir → asarUnpack; then move asarUnpack → asar.unpack",
+        "• Move mac/mas/masDev/win/linux asarUnpack → <platform>.asar.unpack (a platform-level asar replaces the root one, so copy the root asar options into it)",
         "• Move disableSanityCheckAsar → asar.disableSanityCheck",
         "• Move disableAsarIntegrity → asar.disableIntegrity",
-        "• Replace asar: true with an asar object (e.g. asar: {})",
+        "• Replace asar: true with an asar object (e.g. asar: {} or omit entirely - asar is enabled by default)",
         "• Remove appImage.systemIntegration",
+        "• Remove linux.syncDesktopName (the installed .desktop filename is always synced from desktopName in v27)",
         "• Rename snap → snapcraft; nest options under a base-named sub-key (default base: core20)",
-        "• Replace vPrefixedTagName with tagNamePrefix on GitHub publish entries",
-        "• Move extra keys in win.azureSignOptions into an additionalMetadata object",
+        "• Replace vPrefixedTagName with tagNamePrefix on GitHub publish entries ('v' is the default prefix - just like before - but can now be customized with tagNamePrefix); an empty tagNamePrefix is now honored",
+        "• Move win.signtoolOptions → win.sign: { type: 'signtool', ...fields }",
+        "• Move win.azureSignOptions → win.sign: { type: 'azure', ...fields }; move untyped extra keys into win.sign.additionalMetadata",
+        "• Remove win.signAndEditExecutable (resource editing always runs in v27); replace win.signExecutable: false with win.sign: false",
         "• Move helper-bundle-id → mac.helperBundleId",
         "• Replace squirrelWindows.noMsi with squirrelWindows.msi (inverted)",
+        "• Replace squirrelWindows.customSquirrelVendorDir with a toolsets.squirrel custom bundle (it must contain an electron-winstaller/vendor/ subtree)",
+        "• Move nsis/nsisWeb customNsisBinary.debugLogging → installerDebugLogging (it needs a log-enabled custom toolsets.nsis); remove customNsisBinary and customNsisResources, replacing a custom url/checksum with a toolsets.nsis custom bundle (the checksum carries over; the bundle must also contain the NSIS plugins)",
+        "• Move mac/mas/masDev signing fields (identity, entitlements, entitlementsInherit, entitlementsLoginHelper, hardenedRuntime, type, requirements, timestamp, binaries, strictVerify, preAutoEntitlements, provisioningProfile, additionalArguments) into the `sign` object; rename signIgnore → sign.ignore; remove gatekeeperAssess",
+        "• Move mac/mas/masDev mergeASARs / singleArchFiles / x64ArchFiles into the `universal` object",
+        "• Rename electronDownload → electronGet (mirror → mirrorOptions.mirror; isVerifyChecksum:false → unsafelyDisableChecksums:true; drop cache/customDir/customFilename/strictSSL/platform/arch/version/force)",
+        '• Remove toolsets.* entries set to null (unset resolves to "latest"); replace toolsets.appimage "1.0.2" with "1.0.3"',
         "• Move root-level package.json directories → build.directories",
+        "",
+        "• For programmatic configs (JS/TS/MJS/CJS), apply the above changes manually to your config object",
+        "• For additional guidance, check the migration walkthrough: https://www.electron.build/docs/migration/v26-to-v27",
+        "• Full list of breaking changes: https://www.electron.build/docs/migration/v27-breaking-changes",
     ];
     for (const step of steps) {
         process.stdout.write(`  ${step}\n`);