@nextclaw/service 0.1.1

package/dist/commands/service/services/autostart/windows-task-autostart.service.js

@@ -0,0 +1,403 @@
+import { HostAutostartRuntimeService } from "./host-autostart-runtime.service.js";
+import { spawn } from "node:child_process";
+import { win32 } from "node:path";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+//#region src/commands/service/services/autostart/windows-task-autostart.service.ts
+const DEFAULT_TASK_NAME = "NextClaw Host Autostart";
+const SUPPORTED_PLATFORM = "win32";
+var WindowsTaskAutostartService = class {
+	platform;
+	pathExists;
+	ensureDir;
+	writeFile;
+	removeFile;
+	runCommandImpl;
+	runtimeService;
+	constructor(options = {}) {
+		this.platform = options.platform ?? process.platform;
+		this.pathExists = options.existsSync ?? existsSync;
+		this.ensureDir = options.mkdirSync ?? mkdirSync;
+		this.writeFile = options.writeFileSync ?? writeFileSync;
+		this.removeFile = options.rmSync ?? rmSync;
+		this.runCommandImpl = options.runCommand ?? defaultRunCommand;
+		this.runtimeService = options.runtimeService ?? new HostAutostartRuntimeService();
+	}
+	install = async (scope, options = {}) => {
+		const plan = this.buildPlan();
+		if (!this.isSupported()) return this.createUnsupportedInstallResult(scope, Boolean(options.dryRun));
+		if (scope === "system") return this.createUnsupportedInstallResult(scope, Boolean(options.dryRun), "Windows task autostart currently supports --user only.");
+		const actions = [
+			`write launcher script ${plan.resourcePath}`,
+			`register scheduled task ${plan.resourceName}`,
+			`start scheduled task ${plan.resourceName}`
+		];
+		try {
+			if (!options.dryRun) {
+				this.ensureDir(win32.dirname(plan.resourcePath), { recursive: true });
+				this.ensureDir(win32.dirname(plan.logPath), { recursive: true });
+				this.writeFile(plan.resourcePath, plan.launcherContent);
+				await this.runCheckedPowerShell(this.renderInstallScript(plan));
+			}
+		} catch (error) {
+			return {
+				ok: false,
+				dryRun: Boolean(options.dryRun),
+				scope,
+				hostOwner: plan.hostOwner,
+				resourceName: plan.resourceName,
+				resourcePath: plan.resourcePath,
+				homeDir: plan.homeDir,
+				command: plan.command,
+				logHint: plan.logHint,
+				actions,
+				reasonIfUnavailable: error instanceof Error ? error.message : "windows task install failed."
+			};
+		}
+		return {
+			ok: true,
+			dryRun: Boolean(options.dryRun),
+			scope,
+			hostOwner: plan.hostOwner,
+			resourceName: plan.resourceName,
+			resourcePath: plan.resourcePath,
+			homeDir: plan.homeDir,
+			command: plan.command,
+			logHint: plan.logHint,
+			actions,
+			reasonIfUnavailable: null
+		};
+	};
+	uninstall = async (scope, options = {}) => {
+		const plan = this.buildPlan();
+		if (!this.isSupported()) return this.createUnsupportedUninstallResult(scope, Boolean(options.dryRun));
+		if (scope === "system") return this.createUnsupportedUninstallResult(scope, Boolean(options.dryRun), "Windows task autostart currently supports --user only.");
+		const installed = (await this.readTaskInfo(plan.resourceName))?.installed ?? false;
+		const actions = [`unregister scheduled task ${plan.resourceName}`, `remove launcher script ${plan.resourcePath}`];
+		if (!installed && !this.pathExists(plan.resourcePath)) return {
+			ok: true,
+			dryRun: Boolean(options.dryRun),
+			scope,
+			hostOwner: plan.hostOwner,
+			resourceName: plan.resourceName,
+			resourcePath: plan.resourcePath,
+			removed: false,
+			logHint: plan.logHint,
+			actions: ["no installed scheduled task or launcher script found"],
+			reasonIfUnavailable: null
+		};
+		try {
+			if (!options.dryRun) {
+				if (installed) await this.runCheckedPowerShell(this.renderUninstallScript(plan.resourceName));
+				this.removeFile(plan.resourcePath, { force: true });
+			}
+		} catch (error) {
+			return {
+				ok: false,
+				dryRun: Boolean(options.dryRun),
+				scope,
+				hostOwner: plan.hostOwner,
+				resourceName: plan.resourceName,
+				resourcePath: plan.resourcePath,
+				removed: false,
+				logHint: plan.logHint,
+				actions,
+				reasonIfUnavailable: error instanceof Error ? error.message : "windows task uninstall failed."
+			};
+		}
+		return {
+			ok: true,
+			dryRun: Boolean(options.dryRun),
+			scope,
+			hostOwner: plan.hostOwner,
+			resourceName: plan.resourceName,
+			resourcePath: plan.resourcePath,
+			removed: true,
+			logHint: plan.logHint,
+			actions,
+			reasonIfUnavailable: null
+		};
+	};
+	status = async (requestedScope) => {
+		const plan = this.buildPlan();
+		if (!this.isSupported()) return this.createUnsupportedStatus();
+		if (requestedScope === "system") return this.createUnsupportedStatus("Windows task autostart currently supports --user only.");
+		const taskInfo = await this.readTaskInfo(plan.resourceName);
+		return {
+			supported: true,
+			installed: taskInfo?.installed ?? false,
+			enabled: taskInfo?.enabled ?? false,
+			active: taskInfo?.active ?? false,
+			scope: "user",
+			hostOwner: plan.hostOwner,
+			resourceName: plan.resourceName,
+			resourcePath: plan.resourcePath,
+			homeDir: plan.homeDir,
+			command: plan.command,
+			logHint: plan.logHint,
+			reasonIfUnavailable: null
+		};
+	};
+	doctor = async (requestedScope) => {
+		const status = await this.status(requestedScope);
+		const plan = this.buildPlan();
+		const taskInfo = await this.readTaskInfo(plan.resourceName);
+		const checks = [
+			this.createPlatformCheck(status),
+			this.createTaskCheck(status, taskInfo, plan.resourceName),
+			this.createLauncherScriptCheck(plan.resourcePath),
+			this.createExecPathCheck(plan.launch.command),
+			this.createHomeDirCheck(plan.homeDir),
+			...this.createInstalledDoctorChecks(status, taskInfo)
+		];
+		return {
+			status,
+			checks,
+			exitCode: checks.some((check) => check.status === "fail" || check.status === "warn") ? 1 : 0
+		};
+	};
+	isSupported = () => {
+		return this.platform === SUPPORTED_PLATFORM;
+	};
+	createUnsupportedStatus = (reason = "windows task autostart currently supports Windows only.") => {
+		return {
+			supported: false,
+			installed: false,
+			enabled: null,
+			active: null,
+			scope: null,
+			hostOwner: null,
+			resourceName: null,
+			resourcePath: null,
+			homeDir: null,
+			command: null,
+			logHint: null,
+			reasonIfUnavailable: reason
+		};
+	};
+	createUnsupportedInstallResult = (scope, dryRun, reason = "windows task autostart currently supports Windows only.") => {
+		const plan = this.buildPlan();
+		const includePlan = this.isSupported();
+		return {
+			ok: false,
+			dryRun,
+			scope,
+			hostOwner: includePlan ? plan.hostOwner : "windows-logon-task",
+			resourceName: includePlan ? plan.resourceName : DEFAULT_TASK_NAME,
+			resourcePath: includePlan ? plan.resourcePath : null,
+			homeDir: includePlan ? plan.homeDir : null,
+			command: includePlan ? plan.command : null,
+			logHint: includePlan ? plan.logHint : null,
+			actions: [],
+			reasonIfUnavailable: reason
+		};
+	};
+	createUnsupportedUninstallResult = (scope, dryRun, reason = "windows task autostart currently supports Windows only.") => {
+		const plan = this.buildPlan();
+		const includePlan = this.isSupported();
+		return {
+			ok: false,
+			dryRun,
+			scope,
+			hostOwner: includePlan ? plan.hostOwner : "windows-logon-task",
+			resourceName: includePlan ? plan.resourceName : DEFAULT_TASK_NAME,
+			resourcePath: includePlan ? plan.resourcePath : null,
+			removed: false,
+			logHint: includePlan ? plan.logHint : null,
+			actions: [],
+			reasonIfUnavailable: reason
+		};
+	};
+	createPlatformCheck = (status) => {
+		return {
+			name: "platform",
+			status: status.supported ? "pass" : "fail",
+			detail: status.supported ? "windows supported" : status.reasonIfUnavailable ?? "unsupported platform"
+		};
+	};
+	createTaskCheck = (status, taskInfo, taskName) => {
+		return {
+			name: "task",
+			status: status.installed ? "pass" : "warn",
+			detail: taskInfo?.taskPath ?? taskName
+		};
+	};
+	createLauncherScriptCheck = (resourcePath) => {
+		return {
+			name: "launcher-script",
+			status: this.pathExists(resourcePath) ? "pass" : "warn",
+			detail: resourcePath
+		};
+	};
+	createExecPathCheck = (commandPath) => {
+		return {
+			name: "exec-path",
+			status: this.pathExists(commandPath) ? "pass" : "fail",
+			detail: commandPath
+		};
+	};
+	createHomeDirCheck = (homeDir) => {
+		return {
+			name: "home-dir",
+			status: this.pathExists(homeDir) ? "pass" : "warn",
+			detail: homeDir
+		};
+	};
+	createInstalledDoctorChecks = (status, taskInfo) => {
+		if (!status.installed) return [];
+		return [
+			{
+				name: "enabled",
+				status: status.enabled === false ? "warn" : "pass",
+				detail: status.enabled === false ? "scheduled task disabled" : "scheduled task enabled"
+			},
+			{
+				name: "active",
+				status: status.active ? "pass" : "warn",
+				detail: taskInfo?.state ?? (status.active ? "Running" : "Not running")
+			},
+			this.createLastTaskResultCheck(taskInfo)
+		];
+	};
+	createLastTaskResultCheck = (taskInfo) => {
+		const lastTaskResult = taskInfo?.lastTaskResult;
+		return {
+			name: "last-task-result",
+			status: lastTaskResult === null || lastTaskResult === void 0 || lastTaskResult === 0 ? "pass" : "warn",
+			detail: lastTaskResult === null || lastTaskResult === void 0 ? "no recorded task result" : String(lastTaskResult)
+		};
+	};
+	buildPlan = () => {
+		const launch = this.runtimeService.resolveForegroundServeLaunch();
+		const homeDir = launch.homeDir;
+		const resourcePath = win32.resolve(homeDir, "autostart", "nextclaw-host-autostart.cmd");
+		const logPath = win32.resolve(homeDir, "logs", "host-autostart", "windows-task.log");
+		return {
+			launch,
+			homeDir,
+			hostOwner: "windows-logon-task",
+			resourceName: DEFAULT_TASK_NAME,
+			resourcePath,
+			logPath,
+			command: `cmd.exe /d /c "${resourcePath}"`,
+			logHint: `Get-Content -Path '${logPath.replace(/'/g, "''")}' -Wait`,
+			launcherContent: this.renderLauncher({
+				launch,
+				homeDir,
+				logPath
+			}),
+			actionExecute: "cmd.exe",
+			actionArguments: `/d /c "${resourcePath}"`
+		};
+	};
+	renderLauncher = (params) => {
+		const { launch, homeDir, logPath } = params;
+		const args = launch.args.map((value) => `"${this.escapeBatchValue(value)}"`).join(" ");
+		return [
+			"@echo off",
+			"setlocal",
+			`set "NEXTCLAW_HOME=${this.escapeBatchValue(homeDir)}"`,
+			`cd /d "${this.escapeBatchValue(homeDir)}"`,
+			`"${this.escapeBatchValue(launch.command)}" ${args} >> "${this.escapeBatchValue(logPath)}" 2>&1`,
+			""
+		].join("\r\n");
+	};
+	escapeBatchValue = (value) => {
+		return value.replace(/"/g, "\"\"");
+	};
+	renderInstallScript = (plan) => {
+		return [
+			`$taskName = '${plan.resourceName.replace(/'/g, "''")}'`,
+			`$userId = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name`,
+			`$action = New-ScheduledTaskAction -Execute 'cmd.exe' -Argument '/d /c "${plan.resourcePath.replace(/'/g, "''")}"'`,
+			"$trigger = New-ScheduledTaskTrigger -AtLogOn",
+			"$principal = New-ScheduledTaskPrincipal -UserId $userId -LogonType InteractiveToken -RunLevel Limited",
+			"$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries",
+			"Register-ScheduledTask -TaskName $taskName -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Force | Out-Null",
+			"Start-ScheduledTask -TaskName $taskName"
+		].join("\n");
+	};
+	renderUninstallScript = (taskName) => {
+		return [
+			`$task = Get-ScheduledTask -TaskName '${taskName.replace(/'/g, "''")}' -ErrorAction SilentlyContinue`,
+			"if ($null -ne $task) {",
+			"  Unregister-ScheduledTask -TaskName $task.TaskName -Confirm:$false",
+			"}"
+		].join("\n");
+	};
+	readTaskInfo = async (taskName) => {
+		const result = await this.runPowerShell(this.renderStatusScript(taskName));
+		if (result.code !== 0) return null;
+		const payload = result.stdout.trim();
+		if (!payload) return null;
+		return JSON.parse(payload);
+	};
+	renderStatusScript = (taskName) => {
+		return [
+			`$task = Get-ScheduledTask -TaskName '${taskName.replace(/'/g, "''")}' -ErrorAction SilentlyContinue`,
+			"if ($null -eq $task) {",
+			"  [pscustomobject]@{ installed = $false; enabled = $false; active = $false; state = $null; taskPath = $null; lastTaskResult = $null } | ConvertTo-Json -Compress",
+			"  exit 0",
+			"}",
+			"$info = Get-ScheduledTaskInfo -TaskName $task.TaskName",
+			"[pscustomobject]@{",
+			"  installed = $true",
+			"  enabled = [bool]$task.Settings.Enabled",
+			"  active = ([string]$task.State -eq 'Running')",
+			"  state = [string]$task.State",
+			"  taskPath = [string]$task.TaskPath",
+			"  lastTaskResult = [int]$info.LastTaskResult",
+			"} | ConvertTo-Json -Compress"
+		].join("\n");
+	};
+	runCheckedPowerShell = async (script) => {
+		const result = await this.runPowerShell(script);
+		if (result.code === 0) return;
+		const detail = result.stderr || result.stdout || `exit code ${result.code}`;
+		throw new Error(`PowerShell command failed: ${detail}`);
+	};
+	runPowerShell = async (script) => {
+		const encodedScript = Buffer.from(script, "utf16le").toString("base64");
+		return await this.runCommandImpl("powershell", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-ExecutionPolicy",
+			"Bypass",
+			"-EncodedCommand",
+			encodedScript
+		]);
+	};
+};
+const defaultRunCommand = async (command, args) => {
+	return await new Promise((resolvePromise, rejectPromise) => {
+		const child = spawn(command, args, {
+			env: process.env,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.setEncoding("utf-8");
+		child.stderr?.setEncoding("utf-8");
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk;
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk;
+		});
+		child.on("error", (error) => {
+			rejectPromise(error);
+		});
+		child.on("close", (code) => {
+			resolvePromise({
+				code: code ?? 1,
+				stdout: stdout.trim(),
+				stderr: stderr.trim()
+			});
+		});
+	});
+};
+//#endregion
+export { WindowsTaskAutostartService };

package/dist/commands/service/types/autostart/host-autostart.types.d.ts

@@ -0,0 +1,64 @@
+//#region src/commands/service/types/autostart/host-autostart.types.d.ts
+type HostAutostartScope = "user" | "system";
+type HostAutostartOwner = "systemd-user-service" | "systemd-system-service" | "launchd-launch-agent" | "windows-logon-task";
+type HostAutostartRunCommandResult = {
+  code: number;
+  stdout: string;
+  stderr: string;
+};
+type HostAutostartRunCommand = (command: string, args: string[]) => Promise<HostAutostartRunCommandResult>;
+type HostAutostartStatus = {
+  supported: boolean;
+  installed: boolean;
+  enabled: boolean | null;
+  active: boolean | null;
+  scope: HostAutostartScope | null;
+  hostOwner: HostAutostartOwner | null;
+  resourceName: string | null;
+  resourcePath: string | null;
+  homeDir: string | null;
+  command: string | null;
+  logHint: string | null;
+  reasonIfUnavailable: string | null;
+};
+type HostAutostartCheck = {
+  name: string;
+  status: "pass" | "warn" | "fail";
+  detail: string;
+};
+type HostAutostartDoctorReport = {
+  status: HostAutostartStatus;
+  checks: HostAutostartCheck[];
+  exitCode: number;
+};
+type HostAutostartInstallResult = {
+  ok: boolean;
+  dryRun: boolean;
+  scope: HostAutostartScope | null;
+  hostOwner: HostAutostartOwner | null;
+  resourceName: string | null;
+  resourcePath: string | null;
+  homeDir: string | null;
+  command: string | null;
+  logHint: string | null;
+  actions: string[];
+  reasonIfUnavailable: string | null;
+};
+type HostAutostartUninstallResult = {
+  ok: boolean;
+  dryRun: boolean;
+  scope: HostAutostartScope | null;
+  hostOwner: HostAutostartOwner | null;
+  resourceName: string | null;
+  resourcePath: string | null;
+  removed: boolean;
+  logHint: string | null;
+  actions: string[];
+  reasonIfUnavailable: string | null;
+};
+type SystemdScopeFlags = {
+  user?: boolean;
+  system?: boolean;
+};
+//#endregion
+export { HostAutostartCheck, HostAutostartDoctorReport, HostAutostartInstallResult, HostAutostartOwner, HostAutostartRunCommand, HostAutostartRunCommandResult, HostAutostartScope, HostAutostartStatus, HostAutostartUninstallResult, SystemdScopeFlags };

package/dist/commands/service/types/autostart/host-autostart.types.js

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

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { AccountCommandOptions, AccountSetUsernameCommandOptions, AgentCommandOptions, AgentsListCommandOptions, AgentsNewCommandOptions, AgentsRemoveCommandOptions, AgentsRuntimesCommandOptions, AgentsUpdateCommandOptions, ChannelsAddOptions, ChannelsLoginOptions, CompanionDisableCommandOptions, CompanionEnableCommandOptions, CompanionStartCommandOptions, CompanionStatusCommandOptions, CompanionStopCommandOptions, ConfigGetOptions, ConfigSetOptions, CronAddOptions, DoctorCommandOptions, GatewayCommandOptions, HealthProbe, LoginCommandOptions, LogsTailCommandOptions, MarketplaceSkillsRecommendCommandOptions, MarketplaceSkillsSearchCommandOptions, McpAddCommandOptions, McpDoctorOptions, McpListOptions, PluginsInfoOptions, PluginsInstallOptions, PluginsListOptions, PluginsUninstallOptions, RemoteConnectCommandOptions, RemoteDoctorCommandOptions, RemoteEnableCommandOptions, RemoteStatusCommandOptions, RequestRestartParams, RuntimeStatusReport, SecretsApplyOptions, SecretsAuditOptions, SecretsConfigureOptions, SecretsReloadOptions, ServiceAutostartCommandOptions, SkillsInfoCommandOptions, SkillsInstalledCommandOptions, StartCommandOptions, StatusCommandOptions, UiCommandOptions, UpdateCommandOptions, UsageCommandOptions } from "./shared/types/cli.types.js";
+import { NextclawServiceRuntime, NextclawServiceRuntimeOptions, runNextclawNpmRuntimeLauncher } from "./service-runtime.service.js";
+import { readLearningLoopRuntimeConfig } from "@nextclaw/kernel";
+export { AccountCommandOptions, AccountSetUsernameCommandOptions, AgentCommandOptions, AgentsListCommandOptions, AgentsNewCommandOptions, AgentsRemoveCommandOptions, AgentsRuntimesCommandOptions, AgentsUpdateCommandOptions, ChannelsAddOptions, ChannelsLoginOptions, CompanionDisableCommandOptions, CompanionEnableCommandOptions, CompanionStartCommandOptions, CompanionStatusCommandOptions, CompanionStopCommandOptions, ConfigGetOptions, ConfigSetOptions, CronAddOptions, DoctorCommandOptions, GatewayCommandOptions, HealthProbe, LoginCommandOptions, LogsTailCommandOptions, MarketplaceSkillsRecommendCommandOptions, MarketplaceSkillsSearchCommandOptions, McpAddCommandOptions, McpDoctorOptions, McpListOptions, NextclawServiceRuntime, type NextclawServiceRuntimeOptions, PluginsInfoOptions, PluginsInstallOptions, PluginsListOptions, PluginsUninstallOptions, RemoteConnectCommandOptions, RemoteDoctorCommandOptions, RemoteEnableCommandOptions, RemoteStatusCommandOptions, RequestRestartParams, RuntimeStatusReport, SecretsApplyOptions, SecretsAuditOptions, SecretsConfigureOptions, SecretsReloadOptions, ServiceAutostartCommandOptions, SkillsInfoCommandOptions, SkillsInstalledCommandOptions, StartCommandOptions, StatusCommandOptions, UiCommandOptions, UpdateCommandOptions, UsageCommandOptions, readLearningLoopRuntimeConfig, runNextclawNpmRuntimeLauncher };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { NextclawServiceRuntime, runNextclawNpmRuntimeLauncher } from "./service-runtime.service.js";
+import { readLearningLoopRuntimeConfig } from "@nextclaw/kernel";
+export { NextclawServiceRuntime, readLearningLoopRuntimeConfig, runNextclawNpmRuntimeLauncher };

package/dist/launcher/npm-runtime-bundle-layout.store.d.ts

@@ -0,0 +1,23 @@
+import { NpmRuntimeBundlePointer } from "./npm-runtime-bundle.types.js";
+
+//#region src/launcher/npm-runtime-bundle-layout.store.d.ts
+declare class NpmRuntimeBundleLayoutStore {
+  private readonly rootDirectory;
+  constructor(rootDirectory?: string);
+  getRootDir: () => string;
+  getVersionsDir: () => string;
+  getVersionDir: (version: string) => string;
+  getStagingDir: () => string;
+  getCurrentPointerPath: () => string;
+  getPreviousPointerPath: () => string;
+  getStatePath: () => string;
+  ensureLauncherDirs: () => void;
+  readCurrentPointer: () => NpmRuntimeBundlePointer | null;
+  readPreviousPointer: () => NpmRuntimeBundlePointer | null;
+  writeCurrentPointer: (pointer: NpmRuntimeBundlePointer) => void;
+  writePreviousPointer: (pointer: NpmRuntimeBundlePointer) => void;
+  private readPointer;
+  private writePointer;
+}
+//#endregion
+export { NpmRuntimeBundleLayoutStore };

package/dist/launcher/npm-runtime-bundle-layout.store.js

@@ -0,0 +1,37 @@
+import { dirname, join } from "node:path";
+import { getDataDir } from "@nextclaw/core";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+//#region src/launcher/npm-runtime-bundle-layout.store.ts
+var NpmRuntimeBundleLayoutStore = class {
+	constructor(rootDirectory = join(getDataDir(), "launcher", "runtime-bundles")) {
+		this.rootDirectory = rootDirectory;
+	}
+	getRootDir = () => this.rootDirectory;
+	getVersionsDir = () => join(this.rootDirectory, "versions");
+	getVersionDir = (version) => join(this.getVersionsDir(), version);
+	getStagingDir = () => join(this.rootDirectory, "staging");
+	getCurrentPointerPath = () => join(this.rootDirectory, "current.json");
+	getPreviousPointerPath = () => join(this.rootDirectory, "previous.json");
+	getStatePath = () => join(getDataDir(), "launcher", "npm-runtime-update-state.json");
+	ensureLauncherDirs = () => {
+		mkdirSync(this.getVersionsDir(), { recursive: true });
+		mkdirSync(this.getStagingDir(), { recursive: true });
+		mkdirSync(dirname(this.getStatePath()), { recursive: true });
+	};
+	readCurrentPointer = () => this.readPointer(this.getCurrentPointerPath());
+	readPreviousPointer = () => this.readPointer(this.getPreviousPointerPath());
+	writeCurrentPointer = (pointer) => this.writePointer(this.getCurrentPointerPath(), pointer);
+	writePreviousPointer = (pointer) => this.writePointer(this.getPreviousPointerPath(), pointer);
+	readPointer = (pointerPath) => {
+		if (!existsSync(pointerPath)) return null;
+		const parsed = JSON.parse(readFileSync(pointerPath, "utf8"));
+		const version = typeof parsed.version === "string" ? parsed.version.trim() : "";
+		return version ? { version } : null;
+	};
+	writePointer = (pointerPath, pointer) => {
+		mkdirSync(dirname(pointerPath), { recursive: true });
+		writeFileSync(pointerPath, `${JSON.stringify(pointer, null, 2)}\n`, "utf8");
+	};
+};
+//#endregion
+export { NpmRuntimeBundleLayoutStore };

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

@@ -0,0 +1,9 @@
+import { NpmRuntimeBundleManifest } from "./npm-runtime-bundle.types.js";
+
+//#region src/launcher/npm-runtime-bundle-manifest.service.d.ts
+declare class NpmRuntimeBundleManifestReader {
+  readFile: (filePath: string) => NpmRuntimeBundleManifest;
+  parse: (input: unknown, context?: string) => NpmRuntimeBundleManifest;
+}
+//#endregion
+export { NpmRuntimeBundleManifestReader };

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

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from "node:fs";
+//#region src/launcher/npm-runtime-bundle-manifest.service.ts
+function readRequiredString(record, key, context) {
+	const value = record[key];
+	if (typeof value !== "string" || !value.trim()) throw new Error(`${context} missing required string field: ${key}`);
+	return value.trim();
+}
+function readRequiredObject(record, key, context) {
+	const value = record[key];
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${context} missing required object field: ${key}`);
+	return value;
+}
+var NpmRuntimeBundleManifestReader = class {
+	readFile = (filePath) => {
+		if (!existsSync(filePath)) throw new Error(`runtime bundle manifest not found: ${filePath}`);
+		return this.parse(JSON.parse(readFileSync(filePath, "utf8")), filePath);
+	};
+	parse = (input, context = "runtime bundle manifest") => {
+		if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error(`${context} must be an object`);
+		const record = input;
+		const launcherCompatibility = readRequiredObject(record, "launcherCompatibility", context);
+		const entrypoints = readRequiredObject(record, "entrypoints", context);
+		const migrationVersion = Number(record.migrationVersion);
+		if (!Number.isInteger(migrationVersion) || migrationVersion < 0) throw new Error(`${context} has invalid migrationVersion`);
+		return {
+			bundleVersion: readRequiredString(record, "bundleVersion", context),
+			platform: readRequiredString(record, "platform", context),
+			arch: readRequiredString(record, "arch", context),
+			uiVersion: readRequiredString(record, "uiVersion", context),
+			runtimeVersion: readRequiredString(record, "runtimeVersion", context),
+			builtInPluginSetVersion: readRequiredString(record, "builtInPluginSetVersion", context),
+			launcherCompatibility: { minVersion: readRequiredString(launcherCompatibility, "minVersion", `${context}.launcherCompatibility`) },
+			entrypoints: { runtimeScript: readRequiredString(entrypoints, "runtimeScript", `${context}.entrypoints`) },
+			migrationVersion
+		};
+	};
+};
+//#endregion
+export { NpmRuntimeBundleManifestReader };

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

@@ -0,0 +1,47 @@
+import { NpmRuntimeBundleManifest } from "./npm-runtime-bundle.types.js";
+import { NpmRuntimeBundleLayoutStore } from "./npm-runtime-bundle-layout.store.js";
+import { NpmRuntimeBundleManifestReader } from "./npm-runtime-bundle-manifest.service.js";
+import { NpmRuntimeUpdateStateStore } from "./npm-runtime-update-state.store.js";
+
+//#region src/launcher/npm-runtime-bundle.service.d.ts
+type ResolvedNpmRuntimeBundle = {
+  bundleDirectory: string;
+  manifest: NpmRuntimeBundleManifest;
+  runtimeScriptPath: string;
+};
+type NpmRuntimeBundleServiceOptions = {
+  layout: NpmRuntimeBundleLayoutStore;
+  stateStore: NpmRuntimeUpdateStateStore;
+  manifestReader?: NpmRuntimeBundleManifestReader;
+  platform?: NodeJS.Platform;
+  arch?: string;
+  launcherVersion?: string;
+  now?: () => number;
+};
+declare class NpmRuntimeBundleService {
+  private readonly options;
+  private readonly manifestReader;
+  private readonly platform;
+  private readonly arch;
+  private readonly launcherVersion;
+  private readonly now;
+  constructor(options: NpmRuntimeBundleServiceOptions);
+  resolveCurrentBundle: () => ResolvedNpmRuntimeBundle | null;
+  resolveVersion: (version: string) => ResolvedNpmRuntimeBundle;
+  installFromDirectory: (sourceDirectory: string) => Promise<ResolvedNpmRuntimeBundle>;
+  activateVersion: (version: string) => void;
+  pruneRetainedArtifacts: () => Promise<void>;
+  private clearStagingDirectory;
+  private verifyBundle;
+}
+declare function compareNpmRuntimeVersions(left: string, right: string): number;
+declare function resolveEffectiveNpmRuntimeVersion(params: {
+  launcherVersion: string | null;
+  currentBundleVersion: string | null;
+}): string | null;
+declare function shouldPreferPackagedNpmRuntime(params: {
+  launcherVersion: string | null;
+  currentBundleVersion: string | null;
+}): boolean;
+//#endregion
+export { NpmRuntimeBundleService, ResolvedNpmRuntimeBundle, compareNpmRuntimeVersions, resolveEffectiveNpmRuntimeVersion, shouldPreferPackagedNpmRuntime };