@qpjoy/electron-launcher 2.0.0 → 2.2.0

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export { classifyLauncherIpv4Address, diagnoseLauncherHostResolution, type Elect
 export { buildElectronLauncherNetworkOwnershipRegistry, mergedElectronLauncherDnsZones, mergedElectronLauncherReverseProxyRoutes, resolveElectronLauncherDnsOwner, type ElectronLauncherNetworkOwner, type ElectronLauncherNetworkOwnerState, type ElectronLauncherNetworkOwnershipClaim, type ElectronLauncherNetworkOwnershipConflict, type ElectronLauncherNetworkOwnershipEntry, type ElectronLauncherNetworkOwnershipRegistry, type ElectronLauncherNetworkOwnershipResource, type ElectronLauncherNetworkOwnershipRoute } from './network-ownership-registry.js';
 export { applyElectronLauncherStandaloneDataPlane, buildElectronLauncherStandaloneOwnershipClaim, diagnoseElectronLauncherStandaloneDataPlane, readElectronLauncherStandaloneOwnershipState, releaseElectronLauncherStandaloneOwnershipClaim, stopElectronLauncherStandaloneDataPlane, upsertElectronLauncherStandaloneOwnershipClaim, type ElectronLauncherStandaloneDataPlaneApplyInput, type ElectronLauncherStandaloneDataPlaneApplyResult, type ElectronLauncherStandaloneDataPlaneDiagnostics, type ElectronLauncherStandaloneDataPlaneInput, type ElectronLauncherStandaloneDataPlaneProbeTarget, type ElectronLauncherStandaloneDataPlaneSeverity, type ElectronLauncherStandaloneDataPlaneStopInput, type ElectronLauncherStandaloneDataPlaneStopResult, type ElectronLauncherStandaloneDataPlaneState, type ElectronLauncherStandaloneEndpointProbe, type ElectronLauncherStandaloneOwnershipInput, type ElectronLauncherStandaloneOwnershipState, type ElectronLauncherStandaloneRouteProbe } from './standalone-data-plane.js';
 export { createElectronLauncherReleaseUpdater, downloadElectronLauncherReleaseArtifactToFile, type ElectronLauncherArtifactDownloadInput, type ElectronLauncherArtifactDownloadResult, type ElectronLauncherReleaseActivationMode, type ElectronLauncherReleaseArtifactRef, type ElectronLauncherReleasePlan, type ElectronLauncherReleasePolicyDecision, type ElectronLauncherReleaseReportInput, type ElectronLauncherReleaseUpdateMode, type ElectronLauncherReleaseUpdater, type ElectronLauncherReleaseUpdaterOptions, type ElectronLauncherUpdateCheckInput, type ElectronLauncherUpdateCheckResult } from './release-updater.js';
+export { allocateElectronLauncherLocalPort, electronLauncherDefaultBasePort, type ElectronLauncherLocalPortLease, type ElectronLauncherLocalPortRequest } from './local-ports.js';
+export { adoptPendingElectronLauncherPackages, classifyElectronLauncherUpdateArtifact, createElectronLauncherReleaseUpdateExecutor, reportElectronLauncherInstallCompletionIfUpgraded, type ElectronLauncherArtifactActivation, type ElectronLauncherArtifactExecution, type ElectronLauncherNetworkGateState, type ElectronLauncherReleaseUpdateExecutor, type ElectronLauncherUpdateArtifactClass, type ElectronLauncherUpdateExecutionResult, type ElectronLauncherUpdateExecutorOptions, type ElectronLauncherUpdateExecutorPhase } from './release-update-executor.js';
 export declare const ELECTRON_LAUNCHER_PACKAGE_NAME = "@qpjoy/electron-launcher";
 export type ElectronLauncherMode = LauncherProductMode;
 export interface ElectronLauncherOptions extends LauncherClientOptions {

package/dist/index.js

@@ -6,6 +6,8 @@ export { classifyLauncherIpv4Address, diagnoseLauncherHostResolution } from './n
 export { buildElectronLauncherNetworkOwnershipRegistry, mergedElectronLauncherDnsZones, mergedElectronLauncherReverseProxyRoutes, resolveElectronLauncherDnsOwner } from './network-ownership-registry.js';
 export { applyElectronLauncherStandaloneDataPlane, buildElectronLauncherStandaloneOwnershipClaim, diagnoseElectronLauncherStandaloneDataPlane, readElectronLauncherStandaloneOwnershipState, releaseElectronLauncherStandaloneOwnershipClaim, stopElectronLauncherStandaloneDataPlane, upsertElectronLauncherStandaloneOwnershipClaim } from './standalone-data-plane.js';
 export { createElectronLauncherReleaseUpdater, downloadElectronLauncherReleaseArtifactToFile } from './release-updater.js';
+export { allocateElectronLauncherLocalPort, electronLauncherDefaultBasePort } from './local-ports.js';
+export { adoptPendingElectronLauncherPackages, classifyElectronLauncherUpdateArtifact, createElectronLauncherReleaseUpdateExecutor, reportElectronLauncherInstallCompletionIfUpgraded } from './release-update-executor.js';
 export const ELECTRON_LAUNCHER_PACKAGE_NAME = '@qpjoy/electron-launcher';
 export function createElectronLauncher(options) {
     const mode = options.mode ?? 'embed';

package/dist/local-ports.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Local port allocation for standalone launcher products (docs/19 §4.3).
+ *
+ * Fixed defaults like mihomo 23457/23458 collide as soon as two standalone
+ * products (MX-H2I + Luopan) run the same runtime on one machine. Each
+ * product/service pair instead derives a stable base port from a hash, probes
+ * it, and scans upward past ports that are already in use. The result is
+ * stable per machine as long as the same product asks first, and never
+ * silently reuses a port another product is listening on.
+ */
+export interface ElectronLauncherLocalPortRequest {
+    /** Product that owns the listener, e.g. `mx-h2i`, `luopan`. */
+    productId: string;
+    /** Service label inside the product, e.g. `mihomo-mixed`, `mihomo-controller`, `pac-edge`. */
+    service: string;
+    /** Previously persisted port; reused when still free. */
+    preferredPort?: number | null;
+    /** Override the hash-derived base port. */
+    basePort?: number | null;
+    /** How many candidate ports to probe before failing. Default 50. */
+    maxAttempts?: number | null;
+    /** Bind host used for probing. Default 127.0.0.1. */
+    host?: string | null;
+}
+export interface ElectronLauncherLocalPortLease {
+    port: number;
+    source: 'preferred' | 'base' | 'scan';
+    basePort: number;
+    attempts: number;
+}
+export declare function electronLauncherDefaultBasePort(productId: string, service: string): number;
+export declare function allocateElectronLauncherLocalPort(request: ElectronLauncherLocalPortRequest): Promise<ElectronLauncherLocalPortLease>;

package/dist/local-ports.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { createServer } from 'node:net';
+const PORT_RANGE_START = 21000;
+const PORT_RANGE_SIZE = 20000; // 21000-40999, clear of common dev servers and ephemeral churn
+export function electronLauncherDefaultBasePort(productId, service) {
+    const digest = createHash('sha256').update(`${productId}:${service}`).digest();
+    const offset = digest.readUInt32BE(0) % PORT_RANGE_SIZE;
+    return PORT_RANGE_START + offset;
+}
+export async function allocateElectronLauncherLocalPort(request) {
+    const productId = request.productId?.trim();
+    const service = request.service?.trim();
+    if (!productId || !service)
+        throw new Error('allocateElectronLauncherLocalPort requires productId and service');
+    const host = request.host?.trim() || '127.0.0.1';
+    const maxAttempts = normalizeAttempts(request.maxAttempts);
+    const basePort = normalizePort(request.basePort) ?? electronLauncherDefaultBasePort(productId, service);
+    const preferred = normalizePort(request.preferredPort);
+    let attempts = 0;
+    if (preferred) {
+        attempts += 1;
+        if (await portIsFree(host, preferred)) {
+            return { port: preferred, source: 'preferred', basePort, attempts };
+        }
+    }
+    for (let i = 0; i < maxAttempts; i += 1) {
+        const candidate = PORT_RANGE_START + ((basePort - PORT_RANGE_START + i) % PORT_RANGE_SIZE);
+        if (candidate === preferred)
+            continue;
+        attempts += 1;
+        if (await portIsFree(host, candidate)) {
+            return { port: candidate, source: i === 0 ? 'base' : 'scan', basePort, attempts };
+        }
+    }
+    throw new Error(`No free local port for ${productId}/${service} after ${attempts} attempts (base ${basePort})`);
+}
+function portIsFree(host, port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.unref();
+        server.once('error', () => resolve(false));
+        server.listen({ host, port, exclusive: true }, () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+function normalizePort(value) {
+    if (typeof value !== 'number' || !Number.isInteger(value))
+        return null;
+    return value >= 1 && value <= 65535 ? value : null;
+}
+function normalizeAttempts(value) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1)
+        return 50;
+    return Math.min(value, 2000);
+}

package/dist/release-update-executor.d.ts

@@ -0,0 +1,94 @@
+import { type ElectronLauncherReleaseArtifactRef, type ElectronLauncherReleaseUpdater, type ElectronLauncherUpdateCheckResult } from './release-updater.js';
+/**
+ * Update executor for standalone launcher products (docs/17 state machine,
+ * docs/19 §5 pipelines). Electron-free: the product injects the callbacks that
+ * touch its runtime (reload renderer, apply config, open the installer).
+ *
+ *   idle -> checking -> downloading -> verifying -> staged -> activating -> reported
+ *
+ * Activation never runs while the product network is connecting, recovering,
+ * or waiting for a permission prompt; installer activation is always manual.
+ */
+export type ElectronLauncherUpdateExecutorPhase = 'idle' | 'checking' | 'downloading' | 'verifying' | 'staged' | 'activating' | 'reported' | 'failed';
+export type ElectronLauncherNetworkGateState = 'idle' | 'connected' | 'connecting' | 'recovering' | 'permission-required';
+export type ElectronLauncherUpdateArtifactClass = 'config' | 'renderer' | 'npm-package' | 'asar' | 'installer' | 'unknown';
+export interface ElectronLauncherUpdateExecutorOptions {
+    updater: ElectronLauncherReleaseUpdater;
+    /** Product data dir, e.g. Electron `app.getPath('userData')`. */
+    baseDir: string;
+    installId?: string | null;
+    /** Blocks activation while the connection path is busy. Default: always idle. */
+    networkGate?: () => ElectronLauncherNetworkGateState | Promise<ElectronLauncherNetworkGateState>;
+    onPhase?: (phase: ElectronLauncherUpdateExecutorPhase, detail: Record<string, unknown>) => void;
+    /** Push a newly activated config/feature-flag snapshot into the runtime. */
+    applyConfig?: (activePath: string) => void | Promise<void>;
+    /** Reload the renderer from the newly activated bundle path. */
+    applyRenderer?: (activePath: string) => void | Promise<void>;
+    /** Open a downloaded installer through the OS (e.g. shell.openPath). */
+    openInstaller?: (filePath: string) => void | Promise<void>;
+}
+export interface ElectronLauncherArtifactExecution {
+    artifactId: string;
+    artifactClass: ElectronLauncherUpdateArtifactClass;
+    phase: ElectronLauncherUpdateExecutorPhase;
+    stagedPath: string | null;
+    activated: boolean;
+    deferredReason: string | null;
+    error: string | null;
+}
+export interface ElectronLauncherUpdateExecutionResult {
+    releaseId: string | null;
+    executed: boolean;
+    reason: string;
+    artifacts: ElectronLauncherArtifactExecution[];
+}
+interface SlotPointer {
+    version: string;
+    path: string;
+    activatedAt: string;
+}
+export declare function classifyElectronLauncherUpdateArtifact(kind: string | null | undefined): ElectronLauncherUpdateArtifactClass;
+export interface ElectronLauncherArtifactActivation {
+    artifactClass: ElectronLauncherUpdateArtifactClass;
+    activated: boolean;
+    deferredReason: string | null;
+    activePath: string | null;
+}
+export interface ElectronLauncherReleaseUpdateExecutor {
+    execute(check: ElectronLauncherUpdateCheckResult): Promise<ElectronLauncherUpdateExecutionResult>;
+    /**
+     * Activate an artifact that was already downloaded and digest-verified by
+     * the product's own download path. Applies the same gate and slot rules as
+     * `execute`; installer-class artifacts always defer to manual confirmation.
+     */
+    activateStaged(artifact: ElectronLauncherReleaseArtifactRef, stagedPath: string, context?: {
+        releaseId?: string | null;
+    }): Promise<ElectronLauncherArtifactActivation>;
+    /** Manual confirmation step for installer-class artifacts. */
+    openStagedInstaller(artifact: ElectronLauncherReleaseArtifactRef): Promise<string>;
+    /** Roll the given slot back to its previous pointer. */
+    rollback(slot: 'config' | 'renderer'): Promise<SlotPointer | null>;
+}
+export declare function createElectronLauncherReleaseUpdateExecutor(options: ElectronLauncherUpdateExecutorOptions): ElectronLauncherReleaseUpdateExecutor;
+/**
+ * Boot-time adoption of npm-package/asar artifacts staged with
+ * `activatedAt: next-start`. Call before wiring module paths; returns the
+ * packages whose pending pointer was promoted to current.
+ */
+export declare function adoptPendingElectronLauncherPackages(baseDir: string): Promise<SlotPointer[]>;
+/**
+ * Closes the installer loop (docs/19 §5 pipeline 4): on startup, compare the
+ * running version with the last recorded one; when it changed, report
+ * `installer-completed` so Release Center can mark this install as upgraded.
+ */
+export declare function reportElectronLauncherInstallCompletionIfUpgraded(input: {
+    updater: ElectronLauncherReleaseUpdater;
+    baseDir: string;
+    currentVersion: string;
+    installId?: string | null;
+}): Promise<{
+    upgraded: boolean;
+    from: string | null;
+    to: string;
+}>;
+export {};

package/dist/release-update-executor.js

@@ -0,0 +1,295 @@
+import { copyFile, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { downloadElectronLauncherReleaseArtifactToFile } from './release-updater.js';
+const SLOTS_DIR = 'update-slots';
+const STAGING_DIR = 'updates';
+export function classifyElectronLauncherUpdateArtifact(kind) {
+    const value = (kind || '').toLowerCase();
+    if (!value)
+        return 'unknown';
+    if (/installer|dmg|msi|exe-full/.test(value))
+        return 'installer';
+    if (/config|feature-flag|snapshot/.test(value))
+        return 'config';
+    if (/renderer|ui-bundle/.test(value))
+        return 'renderer';
+    if (/asar/.test(value))
+        return 'asar';
+    if (/npm|launcher-package|package-dist/.test(value))
+        return 'npm-package';
+    return 'unknown';
+}
+export function createElectronLauncherReleaseUpdateExecutor(options) {
+    const baseDir = options.baseDir;
+    if (!baseDir?.trim())
+        throw new Error('release update executor requires baseDir');
+    const phase = (value, detail = {}) => {
+        options.onPhase?.(value, detail);
+    };
+    const report = async (status, metadata) => {
+        try {
+            await options.updater.report({ status, installId: options.installId ?? null, metadata });
+        }
+        catch {
+            // Reporting must never break the update path; Internal aggregates gaps as missing evidence.
+        }
+    };
+    const gateState = async () => options.networkGate ? options.networkGate() : 'idle';
+    const activationBlocked = async () => {
+        const state = await gateState();
+        return state === 'connecting' || state === 'recovering' || state === 'permission-required'
+            ? `network state is ${state}`
+            : null;
+    };
+    async function stageArtifact(releaseId, artifact) {
+        const fileName = artifact.url ? basename(new URL(artifact.url).pathname) || artifact.artifactId : artifact.artifactId;
+        const targetPath = join(baseDir, STAGING_DIR, releaseId, fileName);
+        phase('downloading', { artifactId: artifact.artifactId, targetPath });
+        await report('download-started', { artifactId: artifact.artifactId, releaseId });
+        phase('verifying', { artifactId: artifact.artifactId });
+        await downloadElectronLauncherReleaseArtifactToFile({ artifact, targetPath });
+        return targetPath;
+    }
+    async function activateSlot(slot, artifact, stagedPath) {
+        const slotDir = join(baseDir, SLOTS_DIR, slot);
+        await mkdir(slotDir, { recursive: true });
+        const activePath = join(slotDir, `active-${artifact.version}-${basename(stagedPath)}`);
+        const tempPath = `${activePath}.next`;
+        await copyFile(stagedPath, tempPath);
+        await rm(activePath, { force: true });
+        await rename(tempPath, activePath);
+        const current = await readPointer(join(slotDir, 'current.json'));
+        if (current)
+            await writePointer(join(slotDir, 'previous.json'), current);
+        await writePointer(join(slotDir, 'current.json'), {
+            version: artifact.version,
+            path: activePath,
+            activatedAt: new Date().toISOString()
+        });
+        return activePath;
+    }
+    async function performActivation(artifact, stagedPath, releaseId) {
+        const artifactClass = classifyElectronLauncherUpdateArtifact(artifact.kind);
+        const result = {
+            artifactClass,
+            activated: false,
+            deferredReason: null,
+            activePath: null
+        };
+        if (artifactClass === 'installer') {
+            result.deferredReason = 'installer activation is manual';
+            return result;
+        }
+        const blocked = await activationBlocked();
+        if (blocked) {
+            result.deferredReason = blocked;
+            await report('artifact-activation-deferred', { artifactId: artifact.artifactId, releaseId, reason: blocked });
+            return result;
+        }
+        phase('activating', { artifactId: artifact.artifactId, artifactClass });
+        if (artifactClass === 'config') {
+            result.activePath = await activateSlot('config', artifact, stagedPath);
+            await options.applyConfig?.(result.activePath);
+            result.activated = true;
+            await report('artifact-applied', { artifactId: artifact.artifactId, releaseId, artifactClass, path: result.activePath });
+        }
+        else if (artifactClass === 'renderer') {
+            result.activePath = await activateSlot('renderer', artifact, stagedPath);
+            await options.applyRenderer?.(result.activePath);
+            result.activated = true;
+            await report('artifact-applied', { artifactId: artifact.artifactId, releaseId, artifactClass, path: result.activePath });
+        }
+        else if (artifactClass === 'npm-package' || artifactClass === 'asar') {
+            const pendingDir = join(baseDir, 'launcher-packages', artifact.componentId || 'unknown', artifact.version);
+            await mkdir(pendingDir, { recursive: true });
+            const packagePath = join(pendingDir, basename(stagedPath));
+            await copyFile(stagedPath, packagePath);
+            await writePointer(join(baseDir, 'launcher-packages', `${artifact.componentId || 'unknown'}.pending.json`), {
+                version: artifact.version,
+                path: packagePath,
+                activatedAt: 'next-start'
+            });
+            result.activePath = packagePath;
+            result.deferredReason = artifact.restartRequired ? 'restart required' : 'applies on next start';
+            await report('artifact-staged-pending-restart', {
+                artifactId: artifact.artifactId,
+                releaseId,
+                componentId: artifact.componentId,
+                version: artifact.version
+            });
+        }
+        else {
+            result.deferredReason = `unknown artifact kind ${artifact.kind}`;
+        }
+        return result;
+    }
+    return {
+        async execute(check) {
+            phase('checking', { status: check.status });
+            if (check.status !== 'update-available' || !check.plan) {
+                phase('idle', { reason: check.reason });
+                return { releaseId: check.plan?.releaseId ?? null, executed: false, reason: check.reason, artifacts: [] };
+            }
+            const releaseId = check.plan.releaseId;
+            const executions = [];
+            for (const artifact of check.artifacts) {
+                const artifactClass = classifyElectronLauncherUpdateArtifact(artifact.kind);
+                const execution = {
+                    artifactId: artifact.artifactId,
+                    artifactClass,
+                    phase: 'idle',
+                    stagedPath: null,
+                    activated: false,
+                    deferredReason: null,
+                    error: null
+                };
+                executions.push(execution);
+                try {
+                    const stagedPath = await stageArtifact(releaseId, artifact);
+                    execution.stagedPath = stagedPath;
+                    execution.phase = 'staged';
+                    await report(artifactClass === 'installer' ? 'installer-downloaded' : 'artifact-staged', {
+                        artifactId: artifact.artifactId,
+                        releaseId,
+                        artifactClass,
+                        path: stagedPath
+                    });
+                    if (artifactClass === 'installer')
+                        continue; // installer activation is always manual
+                    if (!artifact.autoApply) {
+                        execution.deferredReason = 'manual activation required';
+                        continue;
+                    }
+                    const activation = await performActivation(artifact, stagedPath, releaseId);
+                    execution.activated = activation.activated;
+                    execution.deferredReason = activation.deferredReason;
+                    execution.phase = 'reported';
+                }
+                catch (error) {
+                    execution.phase = 'failed';
+                    execution.error = error instanceof Error ? error.message : String(error);
+                    await report('download-failed', { artifactId: artifact.artifactId, releaseId, error: execution.error });
+                }
+            }
+            phase('reported', { releaseId });
+            return { releaseId, executed: true, reason: check.reason, artifacts: executions };
+        },
+        async activateStaged(artifact, stagedPath, context) {
+            if (!existsSync(stagedPath))
+                throw new Error(`staged artifact not found: ${stagedPath}`);
+            return performActivation(artifact, stagedPath, context?.releaseId ?? null);
+        },
+        async openStagedInstaller(artifact) {
+            const fileName = artifact.url ? basename(new URL(artifact.url).pathname) || artifact.artifactId : artifact.artifactId;
+            const candidates = [join(baseDir, STAGING_DIR)];
+            // staged as updates/<releaseId>/<file>; find the newest match
+            const path = await findStagedFile(candidates[0], fileName);
+            if (!path)
+                throw new Error(`installer not staged: ${fileName}`);
+            await options.openInstaller?.(path);
+            await report('installer-opened', { artifactId: artifact.artifactId, path });
+            return path;
+        },
+        async rollback(slot) {
+            const slotDir = join(baseDir, SLOTS_DIR, slot);
+            const previous = await readPointer(join(slotDir, 'previous.json'));
+            if (!previous)
+                return null;
+            const current = await readPointer(join(slotDir, 'current.json'));
+            await writePointer(join(slotDir, 'current.json'), previous);
+            if (current)
+                await writePointer(join(slotDir, 'previous.json'), current);
+            if (slot === 'config')
+                await options.applyConfig?.(previous.path);
+            if (slot === 'renderer')
+                await options.applyRenderer?.(previous.path);
+            await report('artifact-rolled-back', { slot, version: previous.version, path: previous.path });
+            return previous;
+        }
+    };
+}
+/**
+ * Boot-time adoption of npm-package/asar artifacts staged with
+ * `activatedAt: next-start`. Call before wiring module paths; returns the
+ * packages whose pending pointer was promoted to current.
+ */
+export async function adoptPendingElectronLauncherPackages(baseDir) {
+    const dir = join(baseDir, 'launcher-packages');
+    if (!existsSync(dir))
+        return [];
+    const { readdir } = await import('node:fs/promises');
+    const adopted = [];
+    for (const entry of await readdir(dir)) {
+        if (!entry.endsWith('.pending.json'))
+            continue;
+        const pendingPath = join(dir, entry);
+        const pointer = await readPointer(pendingPath);
+        if (!pointer)
+            continue;
+        const currentPath = join(dir, entry.replace(/\.pending\.json$/, '.current.json'));
+        await writePointer(currentPath, { ...pointer, activatedAt: new Date().toISOString() });
+        await rm(pendingPath, { force: true });
+        adopted.push(pointer);
+    }
+    return adopted;
+}
+/**
+ * Closes the installer loop (docs/19 §5 pipeline 4): on startup, compare the
+ * running version with the last recorded one; when it changed, report
+ * `installer-completed` so Release Center can mark this install as upgraded.
+ */
+export async function reportElectronLauncherInstallCompletionIfUpgraded(input) {
+    const statePath = join(input.baseDir, SLOTS_DIR, 'app-version.json');
+    let previous = null;
+    try {
+        previous = JSON.parse(await readFile(statePath, 'utf8'))?.version ?? null;
+    }
+    catch {
+        previous = null;
+    }
+    await mkdir(join(input.baseDir, SLOTS_DIR), { recursive: true });
+    await writeFile(statePath, JSON.stringify({ version: input.currentVersion, recordedAt: new Date().toISOString() }, null, 2));
+    if (previous && previous !== input.currentVersion) {
+        try {
+            await input.updater.report({
+                status: 'installer-completed',
+                installId: input.installId ?? null,
+                metadata: { from: previous, to: input.currentVersion }
+            });
+        }
+        catch {
+            // Missing completion reports surface as gray-health gaps server-side.
+        }
+        return { upgraded: true, from: previous, to: input.currentVersion };
+    }
+    return { upgraded: false, from: previous, to: input.currentVersion };
+}
+async function findStagedFile(stagingRoot, fileName) {
+    if (!existsSync(stagingRoot))
+        return null;
+    const { readdir, stat } = await import('node:fs/promises');
+    let newest = null;
+    for (const release of await readdir(stagingRoot)) {
+        const candidate = join(stagingRoot, release, fileName);
+        if (!existsSync(candidate))
+            continue;
+        const info = await stat(candidate);
+        if (!newest || info.mtimeMs > newest.mtime)
+            newest = { path: candidate, mtime: info.mtimeMs };
+    }
+    return newest?.path ?? null;
+}
+async function readPointer(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        return parsed && typeof parsed.path === 'string' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writePointer(path, pointer) {
+    await mkdir(join(path, '..'), { recursive: true });
+    await writeFile(path, JSON.stringify(pointer, null, 2));
+}

package/dist/release-updater.d.ts

@@ -96,6 +96,18 @@ export interface ElectronLauncherUpdateCheckResult {
     decision: ElectronLauncherReleasePolicyDecision;
     artifacts: ElectronLauncherReleaseArtifactRef[];
     reason: string;
+    /** Markdown release notes from the server-side decision, when provided. */
+    releaseNotes?: string | null;
+    /** Feature keys granted to this install by the matched plan. */
+    featureFlags?: string[];
+    /** Why this install did (not) receive the release; shown in the update panel. */
+    rollout?: {
+        matchedBy?: string | null;
+        bucket?: number | null;
+        percentage?: number | null;
+    } | null;
+    /** Which check path produced this result. */
+    checkSource?: 'release-check' | 'plans-legacy';
 }
 export interface ElectronLauncherReleaseUpdaterOptions {
     baseUrl: string;

package/dist/release-updater.js

@@ -11,6 +11,28 @@ export function createElectronLauncherReleaseUpdater(options) {
     return {
         async check(input) {
             const checkedAt = new Date().toISOString();
+            // Preferred path: server-side single-install decision (docs/19 §6). The
+            // server owns target lists and rollout bucketing; the full plans list is
+            // being withdrawn to admin-only. Fall back to the legacy flow against
+            // older servers that do not expose /release/check yet.
+            const installId = input.installId ?? options.reportInstallId ?? null;
+            if (installId) {
+                try {
+                    const payload = await requestJson(fetchImpl, joinUrl(baseUrl, '/internal/v1/release/check'), 'POST', {
+                        installId,
+                        userId: input.userId ?? null,
+                        channel: input.channel,
+                        platform: input.platform ?? null,
+                        components: { [input.componentId]: input.currentVersion }
+                    });
+                    if (payload && typeof payload.status === 'string') {
+                        return mapReleaseCheckPayload(payload, input, baseUrl, checkedAt);
+                    }
+                }
+                catch {
+                    // Older server without /release/check; use the legacy plans flow.
+                }
+            }
             const plansPayload = await requestJson(fetchImpl, joinUrl(baseUrl, '/internal/v1/release-management/plans'), 'GET');
             const plans = Array.isArray(plansPayload.plans) ? plansPayload.plans : [];
             const plan = selectReleasePlan(plans, input);
@@ -42,7 +64,8 @@ export function createElectronLauncherReleaseUpdater(options) {
                 artifacts,
                 reason: status === 'blocked'
                     ? plan?.test?.gate?.reason || `release gate is ${gateVerdict}`
-                    : decision.reason
+                    : decision.reason,
+                checkSource: 'plans-legacy'
             };
         },
         async report(input) {
@@ -96,6 +119,53 @@ export async function downloadElectronLauncherReleaseArtifactToFile(input) {
         bytes
     };
 }
+function mapReleaseCheckPayload(payload, input, baseUrl, checkedAt) {
+    const decision = payload.decision ?? {
+        componentKind: input.componentKind || 'app-managed',
+        componentId: input.componentId,
+        currentVersion: input.currentVersion,
+        targetVersion: input.currentVersion,
+        updateAvailable: false,
+        updateMode: 'none',
+        canSkip: true,
+        canDefer: true,
+        requiresGate: false,
+        rollbackRequired: false,
+        reason: payload.reason
+    };
+    const plan = payload.planId && payload.releaseId
+        ? {
+            planId: payload.planId,
+            releaseId: payload.releaseId,
+            environment: 'internal',
+            channel: payload.channel,
+            installId: input.installId ?? null,
+            userId: input.userId ?? null,
+            createdBy: 'release-check',
+            components: decision.componentKind === 'app-managed' ? { app: decision } : { launcher: decision },
+            artifacts: payload.artifacts ?? [],
+            rollout: {
+                percentage: payload.rollout?.percentage ?? undefined,
+                featureKeys: payload.featureFlags ?? []
+            },
+            activation: payload.activation ?? undefined,
+            createdAt: payload.signedAt
+        }
+        : null;
+    return {
+        checkedAt,
+        baseUrl,
+        status: payload.status,
+        plan,
+        decision,
+        artifacts: payload.artifacts ?? [],
+        reason: payload.reason,
+        releaseNotes: payload.releaseNotes ?? null,
+        featureFlags: payload.featureFlags ?? [],
+        rollout: payload.rollout ?? null,
+        checkSource: 'release-check'
+    };
+}
 function selectReleasePlan(plans, input) {
     return plans.find((plan) => {
         if (plan.channel !== input.channel)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qpjoy/electron-launcher",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Product-facing Electron Launcher client for MX Launcher release, update, rollout, AppCenter, and network integration.",
   "type": "module",
   "main": "dist/index.js",
@@ -34,6 +34,14 @@
       "types": "./dist/release-updater.d.ts",
       "import": "./dist/release-updater.js"
     },
+    "./local-ports": {
+      "types": "./dist/local-ports.d.ts",
+      "import": "./dist/local-ports.js"
+    },
+    "./release-update-executor": {
+      "types": "./dist/release-update-executor.d.ts",
+      "import": "./dist/release-update-executor.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -45,10 +53,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@qpjoy/electron-core-wireguard": "^0.2.1",
-    "@qpjoy/mx-launcher-core": "^2.0.0",
-    "@qpjoy/mx-launcher-embed-sdk": "^2.0.0",
-    "@qpjoy/mx-launcher-standalone": "^2.0.0"
+    "@qpjoy/mx-launcher-core": "^2.2.0",
+    "@qpjoy/electron-core-wireguard": "^2.1.0",
+    "@qpjoy/mx-launcher-standalone": "^2.2.0",
+    "@qpjoy/mx-launcher-embed-sdk": "^2.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.7",