@nextclaw/service 0.1.1

package/dist/launcher/npm-runtime-bundle.service.js

@@ -0,0 +1,150 @@
+import { NpmRuntimeBundleManifestReader } from "./npm-runtime-bundle-manifest.service.js";
+import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { cp, readdir, rename, rm } from "node:fs/promises";
+//#region src/launcher/npm-runtime-bundle.service.ts
+function shouldRetryInstallWithCopy(error) {
+	if (!error || typeof error !== "object") return false;
+	const code = "code" in error ? String(error.code) : "";
+	return code === "EXDEV" || code === "EPERM";
+}
+var NpmRuntimeBundleService = class {
+	manifestReader;
+	platform;
+	arch;
+	launcherVersion;
+	now;
+	constructor(options) {
+		this.options = options;
+		this.manifestReader = options.manifestReader ?? new NpmRuntimeBundleManifestReader();
+		this.platform = options.platform ?? process.platform;
+		this.arch = options.arch ?? process.arch;
+		this.launcherVersion = options.launcherVersion?.trim() || null;
+		this.now = options.now ?? Date.now;
+	}
+	resolveCurrentBundle = () => {
+		const pointer = this.options.layout.readCurrentPointer();
+		if (!pointer) return null;
+		return this.resolveVersion(pointer.version);
+	};
+	resolveVersion = (version) => {
+		const bundleDirectory = this.options.layout.getVersionDir(version);
+		const bundle = this.verifyBundle(bundleDirectory);
+		if (bundle.manifest.bundleVersion !== version) throw new Error(`runtime bundle version mismatch: pointer expects ${version} but manifest is ${bundle.manifest.bundleVersion}`);
+		return bundle;
+	};
+	installFromDirectory = async (sourceDirectory) => {
+		this.options.layout.ensureLauncherDirs();
+		const sourceBundle = this.verifyBundle(sourceDirectory);
+		const targetDirectory = this.options.layout.getVersionDir(sourceBundle.manifest.bundleVersion);
+		if (existsSync(targetDirectory)) return this.verifyBundle(targetDirectory);
+		try {
+			await rename(sourceDirectory, targetDirectory);
+			return this.verifyBundle(targetDirectory);
+		} catch (error) {
+			if (!shouldRetryInstallWithCopy(error)) throw error;
+		}
+		const stagingDirectory = join(this.options.layout.getStagingDir(), `${sourceBundle.manifest.bundleVersion}-${this.now()}`);
+		await rm(stagingDirectory, {
+			recursive: true,
+			force: true
+		});
+		try {
+			await cp(sourceDirectory, stagingDirectory, { recursive: true });
+			await rename(stagingDirectory, targetDirectory);
+			return this.verifyBundle(targetDirectory);
+		} catch (error) {
+			await rm(stagingDirectory, {
+				recursive: true,
+				force: true
+			});
+			throw error;
+		}
+	};
+	activateVersion = (version) => {
+		this.resolveVersion(version);
+		const currentPointer = this.options.layout.readCurrentPointer();
+		if (currentPointer) this.options.layout.writePreviousPointer(currentPointer);
+		this.options.layout.writeCurrentPointer({ version });
+		this.options.stateStore.update((state) => ({
+			...state,
+			currentVersion: version,
+			previousVersion: currentPointer?.version ?? state.previousVersion,
+			candidateVersion: version,
+			candidateLaunchCount: 0,
+			downloadedVersion: null,
+			downloadedReleaseNotesUrl: null
+		}));
+	};
+	pruneRetainedArtifacts = async () => {
+		this.options.layout.ensureLauncherDirs();
+		const state = this.options.stateStore.read();
+		const retained = new Set([
+			state.currentVersion,
+			state.previousVersion,
+			state.candidateVersion,
+			state.lastKnownGoodVersion,
+			state.downloadedVersion,
+			this.options.layout.readCurrentPointer()?.version,
+			this.options.layout.readPreviousPointer()?.version
+		].filter((version) => Boolean(version?.trim())));
+		const entries = await readdir(this.options.layout.getVersionsDir(), { withFileTypes: true });
+		for (const entry of entries.sort((left, right) => compareNpmRuntimeVersions(left.name, right.name))) {
+			if (!entry.isDirectory() || retained.has(entry.name)) continue;
+			await rm(join(this.options.layout.getVersionsDir(), entry.name), {
+				recursive: true,
+				force: true
+			});
+		}
+		await this.clearStagingDirectory();
+	};
+	clearStagingDirectory = async () => {
+		const entries = await readdir(this.options.layout.getStagingDir(), { withFileTypes: true });
+		await Promise.all(entries.map(async (entry) => await rm(join(this.options.layout.getStagingDir(), entry.name), {
+			recursive: true,
+			force: true
+		})));
+	};
+	verifyBundle = (bundleDirectory) => {
+		const manifest = this.manifestReader.readFile(resolve(bundleDirectory, "manifest.json"));
+		if (manifest.platform !== this.platform) throw new Error(`runtime bundle platform mismatch: expected ${this.platform} but got ${manifest.platform}`);
+		if (manifest.arch !== this.arch) throw new Error(`runtime bundle arch mismatch: expected ${this.arch} but got ${manifest.arch}`);
+		if (this.launcherVersion && compareNpmRuntimeVersions(this.launcherVersion, manifest.launcherCompatibility.minVersion) < 0) throw new Error(`runtime bundle requires launcher >= ${manifest.launcherCompatibility.minVersion} but current launcher is ${this.launcherVersion}`);
+		const runtimeScriptPath = resolve(bundleDirectory, manifest.entrypoints.runtimeScript);
+		if (!existsSync(runtimeScriptPath)) throw new Error(`runtime bundle script missing: ${runtimeScriptPath}`);
+		return {
+			bundleDirectory,
+			manifest,
+			runtimeScriptPath
+		};
+	};
+};
+function compareNpmRuntimeVersions(left, right) {
+	const leftParts = parseVersionParts(left);
+	const rightParts = parseVersionParts(right);
+	const length = Math.max(leftParts.length, rightParts.length);
+	for (let index = 0; index < length; index += 1) {
+		const leftPart = leftParts[index] ?? 0;
+		const rightPart = rightParts[index] ?? 0;
+		if (leftPart !== rightPart) return leftPart - rightPart;
+	}
+	return left.localeCompare(right);
+}
+function resolveEffectiveNpmRuntimeVersion(params) {
+	const launcherVersion = params.launcherVersion?.trim() || null;
+	const currentBundleVersion = params.currentBundleVersion?.trim() || null;
+	if (!launcherVersion) return currentBundleVersion;
+	if (!currentBundleVersion) return launcherVersion;
+	return compareNpmRuntimeVersions(launcherVersion, currentBundleVersion) > 0 ? launcherVersion : currentBundleVersion;
+}
+function shouldPreferPackagedNpmRuntime(params) {
+	const launcherVersion = params.launcherVersion?.trim() || null;
+	const currentBundleVersion = params.currentBundleVersion?.trim() || null;
+	if (!launcherVersion || !currentBundleVersion) return false;
+	return resolveEffectiveNpmRuntimeVersion(params) === launcherVersion;
+}
+function parseVersionParts(version) {
+	return version.split(/[.-]/).map((part) => Number(part)).map((part) => Number.isFinite(part) ? part : 0);
+}
+//#endregion
+export { NpmRuntimeBundleService, compareNpmRuntimeVersions, resolveEffectiveNpmRuntimeVersion, shouldPreferPackagedNpmRuntime };

package/dist/launcher/npm-runtime-bundle.types.d.ts

@@ -0,0 +1,49 @@
+import { UpdateManifest, UpdateProgress, UpdateSnapshot } from "@nextclaw/kernel/update-contract";
+
+//#region src/launcher/npm-runtime-bundle.types.d.ts
+type NpmRuntimeBundleManifest = {
+  bundleVersion: string;
+  platform: string;
+  arch: string;
+  uiVersion: string;
+  runtimeVersion: string;
+  builtInPluginSetVersion: string;
+  launcherCompatibility: {
+    minVersion: string;
+  };
+  entrypoints: {
+    runtimeScript: string;
+  };
+  migrationVersion: number;
+};
+type NpmRuntimeBundlePointer = {
+  version: string;
+};
+type NpmRuntimeUpdateState = {
+  channel: "stable" | "beta";
+  currentVersion: string | null;
+  previousVersion: string | null;
+  candidateVersion: string | null;
+  candidateLaunchCount: number;
+  lastKnownGoodVersion: string | null;
+  badVersions: string[];
+  lastUpdateCheckAt: string | null;
+  downloadedVersion: string | null;
+  downloadedReleaseNotesUrl: string | null;
+  updatePreferences: {
+    automaticChecks: boolean;
+    autoDownload: boolean;
+  };
+};
+type NpmRuntimeDownloadedUpdate = {
+  manifest: UpdateManifest;
+  downloadedVersion: string;
+  bundleDirectory: string;
+};
+type NpmRuntimeUpdateProgressReporter = (progress: UpdateProgress) => void;
+type NpmRuntimeUpdateCommandResult = {
+  snapshot: UpdateSnapshot;
+  message: string;
+};
+//#endregion
+export { NpmRuntimeBundleManifest, NpmRuntimeBundlePointer, NpmRuntimeDownloadedUpdate, NpmRuntimeUpdateCommandResult, NpmRuntimeUpdateProgressReporter, NpmRuntimeUpdateState };

package/dist/launcher/npm-runtime-bundle.types.js

@@ -0,0 +1 @@
+export {};

package/dist/launcher/npm-runtime-launcher.service.d.ts

@@ -0,0 +1,19 @@
+import { NpmRuntimeBundleLayoutStore } from "./npm-runtime-bundle-layout.store.js";
+
+//#region src/launcher/npm-runtime-launcher.service.d.ts
+type NpmRuntimeLauncherOptions = {
+  argv: string[];
+  env?: NodeJS.ProcessEnv;
+  layout?: NpmRuntimeBundleLayoutStore;
+};
+declare class NpmRuntimeLauncher {
+  private readonly options;
+  private readonly env;
+  private readonly layout;
+  constructor(options: NpmRuntimeLauncherOptions);
+  run: () => never;
+  private resolveRuntimeScriptPath;
+  private resolvePackagedAppEntrypoint;
+}
+//#endregion
+export { NpmRuntimeLauncher };

package/dist/launcher/npm-runtime-launcher.service.js

@@ -0,0 +1,57 @@
+import { NpmRuntimeBundleLayoutStore } from "./npm-runtime-bundle-layout.store.js";
+import { NpmRuntimeBundleService, shouldPreferPackagedNpmRuntime } from "./npm-runtime-bundle.service.js";
+import { inferDefaultNpmRuntimeReleaseChannel } from "./npm-runtime-update-source.service.js";
+import { NpmRuntimeUpdateStateStore } from "./npm-runtime-update-state.store.js";
+import { getPackageVersion as getPackageVersion$1 } from "../shared/utils/package/package-manifest.utils.js";
+import "../shared/utils/cli.utils.js";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { createExternalCommandEnv } from "@nextclaw/core";
+//#region src/launcher/npm-runtime-launcher.service.ts
+var NpmRuntimeLauncher = class {
+	env;
+	layout;
+	constructor(options) {
+		this.options = options;
+		this.env = options.env ?? process.env;
+		this.layout = options.layout ?? new NpmRuntimeBundleLayoutStore();
+	}
+	run = () => {
+		const runtimeScriptPath = this.resolveRuntimeScriptPath();
+		const result = spawnSync(process.execPath, [runtimeScriptPath, ...this.options.argv.slice(2)], {
+			stdio: "inherit",
+			env: {
+				...createExternalCommandEnv(this.env),
+				NEXTCLAW_RUNTIME_BUNDLE_CHILD: "1"
+			}
+		});
+		process.exit(typeof result.status === "number" ? result.status : 1);
+	};
+	resolveRuntimeScriptPath = () => {
+		if (this.env.NEXTCLAW_DISABLE_RUNTIME_BUNDLE_LAUNCHER === "1" || this.env.NEXTCLAW_RUNTIME_BUNDLE_CHILD === "1") return this.resolvePackagedAppEntrypoint();
+		const stateStore = new NpmRuntimeUpdateStateStore(this.layout.getStatePath(), { defaultChannel: inferDefaultNpmRuntimeReleaseChannel(getPackageVersion$1()) });
+		const bundleService = new NpmRuntimeBundleService({
+			layout: this.layout,
+			stateStore,
+			launcherVersion: getPackageVersion$1()
+		});
+		try {
+			const currentBundle = bundleService.resolveCurrentBundle();
+			if (currentBundle && shouldPreferPackagedNpmRuntime({
+				launcherVersion: getPackageVersion$1(),
+				currentBundleVersion: currentBundle.manifest.runtimeVersion ?? currentBundle.manifest.bundleVersion
+			})) return this.resolvePackagedAppEntrypoint();
+			return currentBundle?.runtimeScriptPath ?? this.resolvePackagedAppEntrypoint();
+		} catch (error) {
+			console.error(`Cannot start current runtime bundle: ${error instanceof Error ? error.message : String(error)}`);
+			console.error("Falling back to the packaged npm launcher runtime.");
+			return this.resolvePackagedAppEntrypoint();
+		}
+	};
+	resolvePackagedAppEntrypoint = () => {
+		return resolve(dirname(fileURLToPath(import.meta.url)), "../app/index.js");
+	};
+};
+//#endregion
+export { NpmRuntimeLauncher };

package/dist/launcher/npm-runtime-update-command.service.d.ts

@@ -0,0 +1,12 @@
+import { UpdateCommandOptions } from "../shared/types/cli.types.js";
+import { UpdateSnapshot } from "@nextclaw/kernel/update-contract";
+
+//#region src/launcher/npm-runtime-update-command.service.d.ts
+declare class NpmRuntimeUpdateCommandService {
+  run: (opts: UpdateCommandOptions) => Promise<UpdateSnapshot>;
+  runManaged: (opts: UpdateCommandOptions) => Promise<UpdateSnapshot>;
+  private printProgress;
+  private printSnapshot;
+}
+//#endregion
+export { NpmRuntimeUpdateCommandService };

package/dist/launcher/npm-runtime-update-command.service.js

@@ -0,0 +1,87 @@
+import { NpmRuntimeBundleLayoutStore } from "./npm-runtime-bundle-layout.store.js";
+import { NpmRuntimeBundleService } from "./npm-runtime-bundle.service.js";
+import { NpmRuntimeUpdateSourceService } from "./npm-runtime-update-source.service.js";
+import { NpmRuntimeUpdateStateStore } from "./npm-runtime-update-state.store.js";
+import { getPackageVersion } from "../shared/utils/package/package-manifest.utils.js";
+import "../shared/utils/cli.utils.js";
+import { NpmRuntimeUpdateManager } from "./npm-runtime-update.manager.js";
+import { NpmRuntimeUpdateService } from "./npm-runtime-update.service.js";
+//#region src/launcher/npm-runtime-update-command.service.ts
+var NpmRuntimeUpdateCommandService = class {
+	run = async (opts) => {
+		const snapshot = await this.runManaged(opts);
+		if (opts.json) console.log(JSON.stringify(snapshot, null, 2));
+		else this.printSnapshot(snapshot);
+		return snapshot;
+	};
+	runManaged = async (opts) => {
+		const source = new NpmRuntimeUpdateSourceService();
+		const launcherVersion = getPackageVersion();
+		const channel = source.resolveChannel(opts.channel, launcherVersion);
+		const manifestUrl = source.resolveManifestUrl(channel, opts.manifestUrl);
+		const layout = new NpmRuntimeBundleLayoutStore();
+		const stateStore = new NpmRuntimeUpdateStateStore(layout.getStatePath(), { defaultChannel: channel });
+		const bundleService = new NpmRuntimeBundleService({
+			layout,
+			stateStore,
+			launcherVersion
+		});
+		return await new NpmRuntimeUpdateManager({
+			layout,
+			stateStore,
+			bundleService,
+			updateService: new NpmRuntimeUpdateService({
+				layout,
+				bundleService,
+				launcherVersion,
+				bundlePublicKey: source.resolveBundlePublicKey() ?? void 0
+			}),
+			resolveManifestUrl: () => manifestUrl,
+			launcherVersion,
+			channel
+		}).run({
+			apply: Boolean(opts.apply),
+			checkOnly: Boolean(opts.check),
+			download: opts.download === void 0 ? true : Boolean(opts.download),
+			onProgress: opts.json ? void 0 : this.printProgress
+		});
+	};
+	printProgress = (progress) => {
+		const percent = progress.percent === null ? "" : ` ${progress.percent}%`;
+		const total = progress.totalBytes === null ? "" : ` / ${progress.totalBytes} bytes`;
+		process.stdout.write(`\rDownloading${percent} (${progress.downloadedBytes} bytes${total})`);
+		if (progress.percent === 100) process.stdout.write("\n");
+	};
+	printSnapshot = (snapshot) => {
+		if (snapshot.status === "blocked") {
+			console.error(`Update blocked: ${snapshot.errorMessage ?? snapshot.blockReason ?? "unknown reason"}`);
+			if (snapshot.recoveryCommand) console.error(`Recovery: ${snapshot.recoveryCommand}`);
+			return;
+		}
+		if (snapshot.status === "failed") {
+			console.error(`Update failed: ${snapshot.errorMessage ?? "unknown error"}`);
+			return;
+		}
+		if (snapshot.status === "up-to-date") {
+			console.log(`NextClaw runtime is already up to date (${snapshot.currentVersion ?? snapshot.hostVersion ?? "unknown"}).`);
+			return;
+		}
+		if (snapshot.status === "downloaded") {
+			console.log(`Runtime update downloaded: ${snapshot.downloadedVersion ?? snapshot.availableVersion}`);
+			console.log("Run `nextclaw update --apply` to switch to the downloaded runtime.");
+			return;
+		}
+		if (snapshot.status === "restart-required") {
+			console.log(`Runtime update applied: ${snapshot.currentVersion}`);
+			console.log("Restart the running NextClaw service or start a new CLI process to use it.");
+			return;
+		}
+		if (snapshot.status === "update-available") {
+			console.log(`Runtime update available: ${snapshot.currentVersion ?? "none"} -> ${snapshot.availableVersion}`);
+			return;
+		}
+		console.log(`Update status: ${snapshot.status}`);
+	};
+};
+//#endregion
+export { NpmRuntimeUpdateCommandService };

package/dist/launcher/npm-runtime-update-source.service.d.ts

@@ -0,0 +1,19 @@
+//#region src/launcher/npm-runtime-update-source.service.d.ts
+type NpmRuntimeReleaseChannel = "stable" | "beta";
+type NpmRuntimeUpdateSourceServiceOptions = {
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  arch?: string;
+};
+declare function inferDefaultNpmRuntimeReleaseChannel(launcherVersion?: string | null): NpmRuntimeReleaseChannel;
+declare class NpmRuntimeUpdateSourceService {
+  private readonly env;
+  private readonly platform;
+  private readonly arch;
+  constructor(options?: NpmRuntimeUpdateSourceServiceOptions);
+  resolveChannel: (explicitChannel?: unknown, launcherVersion?: string | null) => NpmRuntimeReleaseChannel;
+  resolveManifestUrl: (channel: NpmRuntimeReleaseChannel, explicitManifestUrl?: unknown) => string | null;
+  resolveBundlePublicKey: () => string | null;
+}
+//#endregion
+export { NpmRuntimeReleaseChannel, NpmRuntimeUpdateSourceService, inferDefaultNpmRuntimeReleaseChannel };

package/dist/launcher/npm-runtime-update-source.service.js

@@ -0,0 +1,57 @@
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+//#region src/launcher/npm-runtime-update-source.service.ts
+const DEFAULT_NPM_RUNTIME_UPDATE_BASE_URL = "https://Peiiii.github.io/nextclaw/npm-runtime-updates";
+function normalizeOptionalString(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed ? trimmed : null;
+}
+function normalizeChannel(value) {
+	return typeof value === "string" && value.trim().toLowerCase() === "beta" ? "beta" : "stable";
+}
+function inferDefaultNpmRuntimeReleaseChannel(launcherVersion) {
+	return typeof launcherVersion === "string" && launcherVersion.toLowerCase().includes("-beta") ? "beta" : "stable";
+}
+function resolvePackagedPublicKeyPath() {
+	const moduleDir = dirname(fileURLToPath(import.meta.url));
+	const candidates = [
+		resolve(moduleDir, "..", "resources", "update-bundle-public.pem"),
+		resolve(moduleDir, "../../..", "resources", "update-bundle-public.pem"),
+		resolve(moduleDir, "../../../..", "resources", "update-bundle-public.pem")
+	];
+	return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
+}
+var NpmRuntimeUpdateSourceService = class {
+	env;
+	platform;
+	arch;
+	constructor(options = {}) {
+		this.env = options.env ?? process.env;
+		this.platform = options.platform ?? process.platform;
+		this.arch = options.arch ?? process.arch;
+	}
+	resolveChannel = (explicitChannel, launcherVersion) => {
+		if (explicitChannel !== void 0 || this.env.NEXTCLAW_UPDATE_CHANNEL !== void 0) return normalizeChannel(explicitChannel ?? this.env.NEXTCLAW_UPDATE_CHANNEL);
+		return inferDefaultNpmRuntimeReleaseChannel(launcherVersion);
+	};
+	resolveManifestUrl = (channel, explicitManifestUrl) => {
+		const manifestUrl = normalizeOptionalString(explicitManifestUrl) ?? normalizeOptionalString(this.env.NEXTCLAW_UPDATE_MANIFEST_URL);
+		if (manifestUrl) return manifestUrl;
+		const baseUrl = normalizeOptionalString(this.env.NEXTCLAW_UPDATE_MANIFEST_BASE_URL) ?? DEFAULT_NPM_RUNTIME_UPDATE_BASE_URL;
+		return new URL(`${channel}/manifest-${channel}-${this.platform}-${this.arch}.json`, `${baseUrl.replace(/\/+$/, "")}/`).toString();
+	};
+	resolveBundlePublicKey = () => {
+		const explicitPublicKey = normalizeOptionalString(this.env.NEXTCLAW_UPDATE_BUNDLE_PUBLIC_KEY);
+		if (explicitPublicKey) return explicitPublicKey;
+		const publicKeyPath = normalizeOptionalString(this.env.NEXTCLAW_UPDATE_BUNDLE_PUBLIC_KEY_PATH);
+		if (!publicKeyPath || !existsSync(publicKeyPath)) {
+			const packagedPublicKeyPath = resolvePackagedPublicKeyPath();
+			return existsSync(packagedPublicKeyPath) ? readFileSync(packagedPublicKeyPath, "utf8").trim() : null;
+		}
+		return readFileSync(publicKeyPath, "utf8").trim();
+	};
+};
+//#endregion
+export { NpmRuntimeUpdateSourceService, inferDefaultNpmRuntimeReleaseChannel };

package/dist/launcher/npm-runtime-update-state.store.d.ts

@@ -0,0 +1,17 @@
+import { NpmRuntimeUpdateState } from "./npm-runtime-bundle.types.js";
+import { NpmRuntimeReleaseChannel } from "./npm-runtime-update-source.service.js";
+
+//#region src/launcher/npm-runtime-update-state.store.d.ts
+type NpmRuntimeUpdateStateStoreOptions = {
+  defaultChannel?: NpmRuntimeReleaseChannel;
+};
+declare class NpmRuntimeUpdateStateStore {
+  private readonly statePath;
+  private readonly defaultChannel;
+  constructor(statePath: string, options?: NpmRuntimeUpdateStateStoreOptions);
+  read: () => NpmRuntimeUpdateState;
+  write: (state: NpmRuntimeUpdateState) => void;
+  update: (updater: (state: NpmRuntimeUpdateState) => NpmRuntimeUpdateState) => NpmRuntimeUpdateState;
+}
+//#endregion
+export { NpmRuntimeUpdateStateStore };

package/dist/launcher/npm-runtime-update-state.store.js

@@ -0,0 +1,92 @@
+import { dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+//#region src/launcher/npm-runtime-update-state.store.ts
+function createDefaultState(channel) {
+	return {
+		channel,
+		currentVersion: null,
+		previousVersion: null,
+		candidateVersion: null,
+		candidateLaunchCount: 0,
+		lastKnownGoodVersion: null,
+		badVersions: [],
+		lastUpdateCheckAt: null,
+		downloadedVersion: null,
+		downloadedReleaseNotesUrl: null,
+		updatePreferences: {
+			automaticChecks: true,
+			autoDownload: true
+		}
+	};
+}
+function normalizeOptionalString(value) {
+	if (typeof value !== "string") return null;
+	const trimmed = value.trim();
+	return trimmed ? trimmed : null;
+}
+function normalizeChannel(value, fallback) {
+	if (typeof value !== "string") return fallback;
+	const trimmed = value.trim().toLowerCase();
+	if (trimmed === "beta") return "beta";
+	if (trimmed === "stable") return "stable";
+	return fallback;
+}
+function normalizeStringArray(value) {
+	if (!Array.isArray(value)) return [];
+	return [...new Set(value.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean))];
+}
+function normalizeUpdatePreferences(value) {
+	const defaultState = createDefaultState("stable");
+	if (!value || typeof value !== "object" || Array.isArray(value)) return { ...defaultState.updatePreferences };
+	const record = value;
+	return {
+		automaticChecks: typeof record.automaticChecks === "boolean" ? record.automaticChecks : defaultState.updatePreferences.automaticChecks,
+		autoDownload: typeof record.autoDownload === "boolean" ? record.autoDownload : defaultState.updatePreferences.autoDownload
+	};
+}
+function normalizeState(input, defaultChannel) {
+	if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("npm runtime update state must be an object");
+	const record = input;
+	const candidateLaunchCount = Number(record.candidateLaunchCount);
+	return {
+		channel: normalizeChannel(record.channel, defaultChannel),
+		currentVersion: normalizeOptionalString(record.currentVersion),
+		previousVersion: normalizeOptionalString(record.previousVersion),
+		candidateVersion: normalizeOptionalString(record.candidateVersion),
+		candidateLaunchCount: Number.isInteger(candidateLaunchCount) && candidateLaunchCount >= 0 ? candidateLaunchCount : 0,
+		lastKnownGoodVersion: normalizeOptionalString(record.lastKnownGoodVersion),
+		badVersions: normalizeStringArray(record.badVersions),
+		lastUpdateCheckAt: normalizeOptionalString(record.lastUpdateCheckAt),
+		downloadedVersion: normalizeOptionalString(record.downloadedVersion),
+		downloadedReleaseNotesUrl: normalizeOptionalString(record.downloadedReleaseNotesUrl),
+		updatePreferences: normalizeUpdatePreferences(record.updatePreferences)
+	};
+}
+var NpmRuntimeUpdateStateStore = class {
+	defaultChannel;
+	constructor(statePath, options = {}) {
+		this.statePath = statePath;
+		this.defaultChannel = options.defaultChannel ?? "stable";
+	}
+	read = () => {
+		if (!existsSync(this.statePath)) {
+			const defaultState = createDefaultState(this.defaultChannel);
+			return {
+				...defaultState,
+				updatePreferences: { ...defaultState.updatePreferences }
+			};
+		}
+		return normalizeState(JSON.parse(readFileSync(this.statePath, "utf8")), this.defaultChannel);
+	};
+	write = (state) => {
+		mkdirSync(dirname(this.statePath), { recursive: true });
+		writeFileSync(this.statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+	};
+	update = (updater) => {
+		const nextState = updater(this.read());
+		this.write(nextState);
+		return nextState;
+	};
+};
+//#endregion
+export { NpmRuntimeUpdateStateStore };

package/dist/launcher/npm-runtime-update.manager.d.ts

@@ -0,0 +1,42 @@
+import { NpmRuntimeBundleLayoutStore } from "./npm-runtime-bundle-layout.store.js";
+import { NpmRuntimeReleaseChannel } from "./npm-runtime-update-source.service.js";
+import { NpmRuntimeUpdateStateStore } from "./npm-runtime-update-state.store.js";
+import { NpmRuntimeBundleService } from "./npm-runtime-bundle.service.js";
+import { NpmRuntimeUpdateService } from "./npm-runtime-update.service.js";
+import { UpdateProgress, UpdateSnapshot } from "@nextclaw/kernel/update-contract";
+
+//#region src/launcher/npm-runtime-update.manager.d.ts
+type NpmRuntimeUpdateManagerOptions = {
+  layout: NpmRuntimeBundleLayoutStore;
+  stateStore: NpmRuntimeUpdateStateStore;
+  bundleService: NpmRuntimeBundleService;
+  updateService: NpmRuntimeUpdateService;
+  resolveManifestUrl: (channel: NpmRuntimeReleaseChannel) => string | null;
+  launcherVersion?: string;
+  channel: NpmRuntimeReleaseChannel;
+  now?: () => Date;
+};
+type NpmRuntimeUpdateActionOptions = {
+  download?: boolean;
+  apply?: boolean;
+  checkOnly?: boolean;
+  onProgress?: (progress: UpdateProgress) => void;
+};
+declare class NpmRuntimeUpdateManager {
+  private readonly options;
+  private readonly launcherVersion;
+  private readonly now;
+  private availableManifest;
+  constructor(options: NpmRuntimeUpdateManagerOptions);
+  getSnapshot: () => UpdateSnapshot;
+  run: (options?: NpmRuntimeUpdateActionOptions) => Promise<UpdateSnapshot>;
+  checkForUpdate: () => Promise<UpdateSnapshot>;
+  downloadUpdate: (onProgress?: (progress: UpdateProgress) => void) => Promise<UpdateSnapshot>;
+  applyDownloadedUpdate: () => UpdateSnapshot;
+  private ensureAvailableManifest;
+  private toSnapshotAfterCheck;
+  private syncStateFromCurrentPointer;
+  private toSnapshotFromState;
+}
+//#endregion
+export { NpmRuntimeUpdateManager };