@nextclaw/app-runtime 0.1.0 → 0.3.0

package/dist/commands/run.controller.js

@@ -1,16 +1,20 @@
-import { AppHostService } from "../host/app-host.service.js";
 import { AppManifestService } from "../manifest/app-manifest.service.js";
+import { AppHostService } from "../host/app-host.service.js";
 import { AppInstanceService } from "../host/app-instance.service.js";
+import { AppInstallationService } from "../install/app-installation.service.js";
 //#region src/commands/run.controller.ts
 var RunCommand = class {
-	constructor(manifestService = new AppManifestService()) {
+	constructor(manifestService = new AppManifestService(), installationService = new AppInstallationService()) {
 		this.manifestService = manifestService;
+		this.installationService = installationService;
 	}
 	run = async (params) => {
-		const { appDirectory, host, port, json, documentGrantMap, write } = params;
-		const bundle = await this.manifestService.load(appDirectory);
+		const { appReference, host, port, json, documentGrantMap, write } = params;
+		const launch = await this.installationService.resolveLaunch(appReference, documentGrantMap);
+		const bundle = await this.manifestService.load(launch.appDirectory);
 		const appInstance = new AppInstanceService(bundle);
-		await appInstance.initialize(documentGrantMap);
+		await appInstance.initialize(launch.documentGrantMap, { appId: launch.appId });
+		await this.installationService.persistGrants(launch.appId, launch.documentGrantMap);
 		const appHost = new AppHostService(appInstance);
 		const hostHandle = await appHost.start({
 			host,
@@ -29,7 +33,11 @@ var RunCommand = class {
 		if (json) {
 			write(`${JSON.stringify({
 				ok: true,
-				host: hostHandle
+				host: hostHandle,
+				app: {
+					appId: launch.appId ?? bundle.manifest.id,
+					appDirectory: launch.appDirectory
+				}
 			}, null, 2)}\n`);
 			return;
 		}

package/dist/commands/uninstall.controller.d.ts

@@ -0,0 +1,15 @@
+import { AppInstallationService } from "../install/app-installation.service.js";
+
+//#region src/commands/uninstall.controller.d.ts
+declare class UninstallCommand {
+  private readonly installationService;
+  constructor(installationService?: AppInstallationService);
+  run: (params: {
+    appId: string;
+    purgeData: boolean;
+    json: boolean;
+    write: (text: string) => void;
+  }) => Promise<void>;
+}
+//#endregion
+export { UninstallCommand };

package/dist/commands/uninstall.controller.js

@@ -0,0 +1,23 @@
+import { AppInstallationService } from "../install/app-installation.service.js";
+//#region src/commands/uninstall.controller.ts
+var UninstallCommand = class {
+	constructor(installationService = new AppInstallationService()) {
+		this.installationService = installationService;
+	}
+	run = async (params) => {
+		const { appId, purgeData, json, write } = params;
+		const result = await this.installationService.uninstall(appId, purgeData);
+		if (json) {
+			write(`${JSON.stringify({
+				ok: true,
+				uninstall: result
+			}, null, 2)}\n`);
+			return;
+		}
+		write(`Uninstalled ${result.appId}\n`);
+		write(`Versions: ${result.removedVersions.join(", ")}\n`);
+		write(`Data removed: ${result.dataRemoved ? "yes" : "no"}\n`);
+	};
+};
+//#endregion
+export { UninstallCommand };

package/dist/commands/update.controller.d.ts

@@ -0,0 +1,16 @@
+import { AppInstallationService } from "../install/app-installation.service.js";
+
+//#region src/commands/update.controller.d.ts
+declare class UpdateCommand {
+  private readonly installationService;
+  constructor(installationService?: AppInstallationService);
+  run: (params: {
+    appId: string;
+    version?: string;
+    registryUrl?: string;
+    json: boolean;
+    write: (text: string) => void;
+  }) => Promise<void>;
+}
+//#endregion
+export { UpdateCommand };

package/dist/commands/update.controller.js

@@ -0,0 +1,29 @@
+import { AppInstallationService } from "../install/app-installation.service.js";
+//#region src/commands/update.controller.ts
+var UpdateCommand = class {
+	constructor(installationService = new AppInstallationService()) {
+		this.installationService = installationService;
+	}
+	run = async (params) => {
+		const { appId, version, registryUrl, json, write } = params;
+		const result = await this.installationService.update(appId, {
+			version,
+			registryUrl
+		});
+		if (json) {
+			write(`${JSON.stringify({
+				ok: true,
+				update: result
+			}, null, 2)}\n`);
+			return;
+		}
+		if (!result.updated) {
+			write(`Already up to date: ${result.appId} ${result.version}\n`);
+			return;
+		}
+		write(`Updated ${result.name} (${result.appId}) ${result.previousVersion} -> ${result.version}\n`);
+		write(`Code: ${result.installDirectory}\n`);
+	};
+};
+//#endregion
+export { UpdateCommand };

package/dist/host/app-instance.service.d.ts

@@ -19,7 +19,9 @@ declare class AppInstanceService {
   private readonly manifestService;
   private permissions?;
   constructor(bundle: AppManifestBundle, permissionsService?: AppPermissionsService, mainRunner?: WasmMainRunnerService, manifestService?: AppManifestService);
-  initialize: (documentGrantMap: AppDocumentGrantMap) => Promise<void>;
+  initialize: (documentGrantMap: AppDocumentGrantMap, context?: {
+    appId?: string;
+  }) => Promise<void>;
   summarizeManifest: () => AppManifestSummary;
   summarizePermissions: () => AppPermissionSummary;
   runAction: (action?: string) => Promise<AppRunResult>;

package/dist/host/app-instance.service.js

@@ -12,8 +12,8 @@ var AppInstanceService = class {
 		this.mainRunner = mainRunner;
 		this.manifestService = manifestService;
 	}
-	initialize = async (documentGrantMap) => {
-		this.permissions = await this.permissionsService.resolve(this.bundle, documentGrantMap);
+	initialize = async (documentGrantMap, context) => {
+		this.permissions = await this.permissionsService.resolve(this.bundle, documentGrantMap, context);
 	};
 	summarizeManifest = () => {
 		return this.manifestService.summarize(this.bundle);

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { AppDocumentAccessMode, AppDocumentAccessScope, AppMainManifest, AppManifest, AppManifestBundle, AppManifestSummary, AppPermissions, AppUiManifest } from "./manifest/app-manifest.types.js";
 import { AppManifestService } from "./manifest/app-manifest.service.js";
-import { AppDocumentGrantMap, AppPermissionSummary, ResolvedDocumentGrant, ResolvedPermissions } from "./permissions/app-permissions.types.js";
+import { AppBundleChecksums, AppBundleExtractResult, AppBundleMetadata, AppBundlePackResult } from "./bundle/app-bundle.types.js";
+import { AppBundleService } from "./bundle/app-bundle.service.js";
+import { AppDocumentGrantMap, AppDocumentGrantMutationResult, AppDocumentGrantState, AppInstalledPermissionState, AppPermissionSummary, ResolvedDocumentGrant, ResolvedPermissions } from "./permissions/app-permissions.types.js";
 import { AppPermissionsService } from "./permissions/app-permissions.service.js";
 import { MainRunRequest, MainRunResult, WasmDocumentSummaryInput } from "./runtime/main-runner.types.js";
 import { MainRunnerService } from "./runtime/main-runner.service.js";
@@ -8,6 +10,28 @@ import { WasmSidecarClientService } from "./sidecar/wasm-sidecar-client.service.
 import { WasmMainRunnerService } from "./runtime/wasm-main-runner.service.js";
 import { AppInstanceService, AppRunResult } from "./host/app-instance.service.js";
 import { HostBridgeServer } from "./bridge/host-bridge.service.js";
+import { AppRuntimeOptionsService, CreateCliOptions, GrantCliOptions, InstallCliOptions, JsonOnlyCliOptions, PackCliOptions, RevokeCliOptions, RuntimeCliOptions, UninstallCliOptions, UpdateCliOptions } from "./cli/app-runtime-options.service.js";
+import { AppRuntimeCliService } from "./cli/app-runtime-cli.service.js";
+import { CreateCommand } from "./commands/create.controller.js";
+import { AppHomeService } from "./paths/app-home.service.js";
+import { AppPublisher, AppRegistryConfig, AppRegistryConfigSnapshot, AppRemoteRegistryDocument, AppRemoteRegistryResolution, AppRemoteRegistryVersion, DEFAULT_APP_REGISTRY_URL } from "./registry/app-remote-registry.types.js";
+import { AppInstallSourceKind, AppRegistry, AppRegistryAppRecord, AppRegistryInstalledVersion } from "./registry/app-registry.types.js";
+import { AppRegistryService } from "./registry/app-registry.service.js";
+import { AppGrantService } from "./permissions/app-grant.service.js";
+import { GrantCommand } from "./commands/grant.controller.js";
+import { AppRegistryConfigService } from "./registry/app-registry-config.service.js";
+import { AppRemoteRegistryClientService } from "./registry/app-remote-registry-client.service.js";
+import { AppInfoResult, AppInstallResult, AppLaunchResolution, AppUninstallResult, AppUpdateResult, InstalledAppListItem } from "./install/app-installation.types.js";
+import { AppInstallationService } from "./install/app-installation.service.js";
+import { InfoCommand } from "./commands/info.controller.js";
+import { InstallCommand } from "./commands/install.controller.js";
+import { ListCommand } from "./commands/list.controller.js";
+import { PackCommand } from "./commands/pack.controller.js";
+import { PermissionsCommand } from "./commands/permissions.controller.js";
+import { RegistryCommand } from "./commands/registry.controller.js";
+import { RevokeCommand } from "./commands/revoke.controller.js";
+import { UpdateCommand } from "./commands/update.controller.js";
+import { UninstallCommand } from "./commands/uninstall.controller.js";
 import { AppHostHandle, AppHostService, AppHostStartOptions } from "./host/app-host.service.js";
 import { UiServerService } from "./ui/ui-server.service.js";
-export { AppDocumentAccessMode, AppDocumentAccessScope, AppDocumentGrantMap, AppHostHandle, AppHostService, AppHostStartOptions, AppInstanceService, AppMainManifest, AppManifest, AppManifestBundle, AppManifestService, AppManifestSummary, AppPermissionSummary, AppPermissions, AppPermissionsService, AppRunResult, AppUiManifest, HostBridgeServer, MainRunRequest, MainRunResult, MainRunnerService, ResolvedDocumentGrant, ResolvedPermissions, UiServerService, WasmDocumentSummaryInput, WasmMainRunnerService, WasmSidecarClientService };
+export { AppBundleChecksums, AppBundleExtractResult, AppBundleMetadata, AppBundlePackResult, AppBundleService, AppDocumentAccessMode, AppDocumentAccessScope, AppDocumentGrantMap, AppDocumentGrantMutationResult, AppDocumentGrantState, AppGrantService, AppHomeService, AppHostHandle, AppHostService, AppHostStartOptions, AppInfoResult, AppInstallResult, AppInstallSourceKind, AppInstallationService, AppInstalledPermissionState, AppInstanceService, AppLaunchResolution, AppMainManifest, AppManifest, AppManifestBundle, AppManifestService, AppManifestSummary, AppPermissionSummary, AppPermissions, AppPermissionsService, AppPublisher, AppRegistry, AppRegistryAppRecord, AppRegistryConfig, AppRegistryConfigService, AppRegistryConfigSnapshot, AppRegistryInstalledVersion, AppRegistryService, AppRemoteRegistryClientService, AppRemoteRegistryDocument, AppRemoteRegistryResolution, AppRemoteRegistryVersion, AppRunResult, AppRuntimeCliService, AppRuntimeOptionsService, AppUiManifest, AppUninstallResult, AppUpdateResult, CreateCliOptions, CreateCommand, DEFAULT_APP_REGISTRY_URL, GrantCliOptions, GrantCommand, HostBridgeServer, InfoCommand, InstallCliOptions, InstallCommand, InstalledAppListItem, JsonOnlyCliOptions, ListCommand, MainRunRequest, MainRunResult, MainRunnerService, PackCliOptions, PackCommand, PermissionsCommand, RegistryCommand, ResolvedDocumentGrant, ResolvedPermissions, RevokeCliOptions, RevokeCommand, RuntimeCliOptions, UiServerService, UninstallCliOptions, UninstallCommand, UpdateCliOptions, UpdateCommand, WasmDocumentSummaryInput, WasmMainRunnerService, WasmSidecarClientService };

package/dist/index.js

@@ -1,10 +1,31 @@
+import { AppManifestService } from "./manifest/app-manifest.service.js";
+import { AppBundleService } from "./bundle/app-bundle.service.js";
 import { HostBridgeServer } from "./bridge/host-bridge.service.js";
+import { CreateCommand } from "./commands/create.controller.js";
 import { UiServerService } from "./ui/ui-server.service.js";
 import { AppHostService } from "./host/app-host.service.js";
-import { AppManifestService } from "./manifest/app-manifest.service.js";
 import { AppPermissionsService } from "./permissions/app-permissions.service.js";
 import { MainRunnerService } from "./runtime/main-runner.service.js";
 import { WasmSidecarClientService } from "./sidecar/wasm-sidecar-client.service.js";
 import { WasmMainRunnerService } from "./runtime/wasm-main-runner.service.js";
 import { AppInstanceService } from "./host/app-instance.service.js";
-export { AppHostService, AppInstanceService, AppManifestService, AppPermissionsService, HostBridgeServer, MainRunnerService, UiServerService, WasmMainRunnerService, WasmSidecarClientService };
+import { AppHomeService } from "./paths/app-home.service.js";
+import { DEFAULT_APP_REGISTRY_URL } from "./registry/app-remote-registry.types.js";
+import { AppRegistryConfigService } from "./registry/app-registry-config.service.js";
+import { AppRemoteRegistryClientService } from "./registry/app-remote-registry-client.service.js";
+import { AppRegistryService } from "./registry/app-registry.service.js";
+import { AppInstallationService } from "./install/app-installation.service.js";
+import { AppGrantService } from "./permissions/app-grant.service.js";
+import { GrantCommand } from "./commands/grant.controller.js";
+import { InfoCommand } from "./commands/info.controller.js";
+import { InstallCommand } from "./commands/install.controller.js";
+import { ListCommand } from "./commands/list.controller.js";
+import { PackCommand } from "./commands/pack.controller.js";
+import { PermissionsCommand } from "./commands/permissions.controller.js";
+import { RegistryCommand } from "./commands/registry.controller.js";
+import { RevokeCommand } from "./commands/revoke.controller.js";
+import { UninstallCommand } from "./commands/uninstall.controller.js";
+import { UpdateCommand } from "./commands/update.controller.js";
+import { AppRuntimeOptionsService } from "./cli/app-runtime-options.service.js";
+import { AppRuntimeCliService } from "./cli/app-runtime-cli.service.js";
+export { AppBundleService, AppGrantService, AppHomeService, AppHostService, AppInstallationService, AppInstanceService, AppManifestService, AppPermissionsService, AppRegistryConfigService, AppRegistryService, AppRemoteRegistryClientService, AppRuntimeCliService, AppRuntimeOptionsService, CreateCommand, DEFAULT_APP_REGISTRY_URL, GrantCommand, HostBridgeServer, InfoCommand, InstallCommand, ListCommand, MainRunnerService, PackCommand, PermissionsCommand, RegistryCommand, RevokeCommand, UiServerService, UninstallCommand, UpdateCommand, WasmMainRunnerService, WasmSidecarClientService };

package/dist/install/app-installation.service.d.ts

@@ -0,0 +1,37 @@
+import { AppManifestService } from "../manifest/app-manifest.service.js";
+import { AppBundleService } from "../bundle/app-bundle.service.js";
+import { AppDocumentGrantMap } from "../permissions/app-permissions.types.js";
+import { AppHomeService } from "../paths/app-home.service.js";
+import { AppRegistryService } from "../registry/app-registry.service.js";
+import { AppRegistryConfigService } from "../registry/app-registry-config.service.js";
+import { AppRemoteRegistryClientService } from "../registry/app-remote-registry-client.service.js";
+import { AppInfoResult, AppInstallResult, AppLaunchResolution, AppUninstallResult, AppUpdateResult, InstalledAppListItem } from "./app-installation.types.js";
+
+//#region src/install/app-installation.service.d.ts
+declare class AppInstallationService {
+  private readonly appHomeService;
+  private readonly bundleService;
+  private readonly manifestService;
+  private readonly registryService;
+  private readonly registryConfigService;
+  private readonly remoteRegistryClient;
+  constructor(appHomeService?: AppHomeService, bundleService?: AppBundleService, manifestService?: AppManifestService, registryService?: AppRegistryService, registryConfigService?: AppRegistryConfigService, remoteRegistryClient?: AppRemoteRegistryClientService);
+  install: (appSource: string, options?: {
+    registryUrl?: string;
+  }) => Promise<AppInstallResult>;
+  update: (appId: string, options?: {
+    version?: string;
+    registryUrl?: string;
+  }) => Promise<AppUpdateResult>;
+  uninstall: (appId: string, purgeData: boolean) => Promise<AppUninstallResult>;
+  list: () => Promise<InstalledAppListItem[]>;
+  info: (appId: string) => Promise<AppInfoResult>;
+  resolveLaunch: (appReference: string, explicitDocumentGrantMap: AppDocumentGrantMap) => Promise<AppLaunchResolution>;
+  persistGrants: (appId: string | undefined, documentGrantMap: AppDocumentGrantMap) => Promise<void>;
+  private resolveInstallSource;
+  private detectLocalSourceType;
+  private parseRegistrySpec;
+  private looksLikePath;
+}
+//#endregion
+export { AppInstallationService };

package/dist/install/app-installation.service.js

@@ -0,0 +1,255 @@
+import { AppManifestService } from "../manifest/app-manifest.service.js";
+import { AppBundleService } from "../bundle/app-bundle.service.js";
+import { AppHomeService } from "../paths/app-home.service.js";
+import { AppRegistryConfigService } from "../registry/app-registry-config.service.js";
+import { AppRemoteRegistryClientService } from "../registry/app-remote-registry-client.service.js";
+import { AppRegistryService } from "../registry/app-registry.service.js";
+import { access, cp, mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+//#region src/install/app-installation.service.ts
+var AppInstallationService = class {
+	constructor(appHomeService = new AppHomeService(), bundleService = new AppBundleService(), manifestService = new AppManifestService(), registryService = new AppRegistryService(appHomeService), registryConfigService = new AppRegistryConfigService(appHomeService), remoteRegistryClient = new AppRemoteRegistryClientService(new AppRegistryConfigService(appHomeService))) {
+		this.appHomeService = appHomeService;
+		this.bundleService = bundleService;
+		this.manifestService = manifestService;
+		this.registryService = registryService;
+		this.registryConfigService = registryConfigService;
+		this.remoteRegistryClient = remoteRegistryClient;
+	}
+	install = async (appSource, options) => {
+		const source = await this.resolveInstallSource(appSource, options?.registryUrl);
+		const tempDirectory = await this.appHomeService.createTemporaryDirectory("napp-install-");
+		try {
+			const bundlePath = source.kind === "directory" ? (await this.bundleService.packAppDirectory({
+				appDirectory: source.appDirectory,
+				outputPath: path.join(tempDirectory, "app.napp")
+			})).bundlePath : source.kind === "bundle" ? source.bundlePath : (await this.remoteRegistryClient.downloadBundle({
+				resolution: source.registryResolution,
+				targetDirectory: tempDirectory
+			})).bundlePath;
+			const extractedDirectory = path.join(tempDirectory, "bundle");
+			await this.bundleService.extractBundle({
+				bundlePath,
+				targetDirectory: extractedDirectory
+			});
+			const manifestBundle = await this.manifestService.load(extractedDirectory);
+			const installDirectory = this.appHomeService.getInstallDirectory(manifestBundle.manifest.id, manifestBundle.manifest.version);
+			if (source.kind === "registry" && manifestBundle.manifest.id !== source.registryResolution.appId) throw new Error(`bundle manifest.appId 与 registry 请求不一致：期望 ${source.registryResolution.appId}，实际 ${manifestBundle.manifest.id}`);
+			const dataDirectory = this.appHomeService.getAppDataDirectory(manifestBundle.manifest.id);
+			await rm(installDirectory, {
+				recursive: true,
+				force: true
+			});
+			await mkdir(path.dirname(installDirectory), { recursive: true });
+			await mkdir(dataDirectory, { recursive: true });
+			await cp(extractedDirectory, installDirectory, { recursive: true });
+			const registryRecord = await this.registryService.upsertInstallation({
+				appId: manifestBundle.manifest.id,
+				name: manifestBundle.manifest.name,
+				description: manifestBundle.manifest.description,
+				version: manifestBundle.manifest.version,
+				installDirectory,
+				dataDirectory,
+				sourceKind: source.kind,
+				sourceRef: source.sourceRef,
+				installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				permissions: manifestBundle.manifest.permissions ?? {},
+				registryUrl: source.kind === "registry" ? source.registryResolution.registryUrl : void 0,
+				bundleUrl: source.kind === "registry" ? source.registryResolution.bundleUrl : void 0,
+				sha256: source.kind === "registry" ? source.registryResolution.sha256 : void 0,
+				publisher: source.kind === "registry" ? source.registryResolution.publisher : void 0
+			});
+			return {
+				appId: registryRecord.appId,
+				name: registryRecord.name,
+				version: registryRecord.activeVersion,
+				installDirectory,
+				dataDirectory,
+				sourceKind: source.kind,
+				sourceRef: source.sourceRef,
+				permissions: registryRecord.installedVersions[registryRecord.activeVersion]?.permissions ?? {},
+				registryUrl: registryRecord.installedVersions[registryRecord.activeVersion]?.registryUrl,
+				bundleUrl: registryRecord.installedVersions[registryRecord.activeVersion]?.bundleUrl,
+				sha256: registryRecord.installedVersions[registryRecord.activeVersion]?.sha256,
+				publisher: registryRecord.installedVersions[registryRecord.activeVersion]?.publisher
+			};
+		} finally {
+			await rm(tempDirectory, {
+				recursive: true,
+				force: true
+			});
+		}
+	};
+	update = async (appId, options) => {
+		const appRecord = await this.registryService.getApp(appId);
+		if (!appRecord) throw new Error(`未找到已安装应用：${appId}`);
+		const activeVersionRecord = appRecord.installedVersions[appRecord.activeVersion];
+		const registryUrl = options?.registryUrl ?? activeVersionRecord?.registryUrl ?? (await this.registryConfigService.getSnapshot()).currentUrl;
+		const resolution = await this.remoteRegistryClient.resolve({
+			appId,
+			version: options?.version,
+			registryUrl
+		});
+		if (resolution.version === appRecord.activeVersion) {
+			if (!activeVersionRecord) throw new Error(`已安装应用缺少激活版本：${appId}`);
+			return {
+				appId: appRecord.appId,
+				name: appRecord.name,
+				version: appRecord.activeVersion,
+				previousVersion: appRecord.activeVersion,
+				installDirectory: activeVersionRecord.installDirectory,
+				dataDirectory: appRecord.dataDirectory,
+				sourceKind: activeVersionRecord.sourceKind,
+				sourceRef: activeVersionRecord.sourceRef,
+				permissions: activeVersionRecord.permissions,
+				registryUrl: activeVersionRecord.registryUrl,
+				bundleUrl: activeVersionRecord.bundleUrl,
+				sha256: activeVersionRecord.sha256,
+				publisher: activeVersionRecord.publisher,
+				updated: false
+			};
+		}
+		return {
+			...await this.install(`${appId}@${resolution.version}`, { registryUrl }),
+			previousVersion: appRecord.activeVersion,
+			updated: true
+		};
+	};
+	uninstall = async (appId, purgeData) => {
+		const appRecord = await this.registryService.removeApp(appId);
+		if (!appRecord) throw new Error(`未找到已安装应用：${appId}`);
+		const removedVersions = Object.keys(appRecord.installedVersions).sort((left, right) => left.localeCompare(right));
+		await Promise.all(Object.values(appRecord.installedVersions).map((versionRecord) => rm(versionRecord.installDirectory, {
+			recursive: true,
+			force: true
+		})));
+		if (purgeData) await rm(appRecord.dataDirectory, {
+			recursive: true,
+			force: true
+		});
+		return {
+			appId,
+			removedVersions,
+			dataRemoved: purgeData
+		};
+	};
+	list = async () => {
+		return (await this.registryService.listApps()).map((appRecord) => ({
+			appId: appRecord.appId,
+			name: appRecord.name,
+			activeVersion: appRecord.activeVersion,
+			sourceKind: appRecord.installedVersions[appRecord.activeVersion]?.sourceKind ?? "directory"
+		}));
+	};
+	info = async (appId) => {
+		const appRecord = await this.registryService.getApp(appId);
+		if (!appRecord) throw new Error(`未找到已安装应用：${appId}`);
+		const installedVersions = Object.values(appRecord.installedVersions).sort((left, right) => left.version.localeCompare(right.version));
+		return {
+			appId: appRecord.appId,
+			name: appRecord.name,
+			description: appRecord.description,
+			activeVersion: appRecord.activeVersion,
+			dataDirectory: appRecord.dataDirectory,
+			installedVersions: installedVersions.map((versionRecord) => ({
+				version: versionRecord.version,
+				installDirectory: versionRecord.installDirectory,
+				sourceKind: versionRecord.sourceKind,
+				sourceRef: versionRecord.sourceRef,
+				installedAt: versionRecord.installedAt,
+				permissions: versionRecord.permissions,
+				registryUrl: versionRecord.registryUrl,
+				bundleUrl: versionRecord.bundleUrl,
+				sha256: versionRecord.sha256,
+				publisher: versionRecord.publisher
+			})),
+			grants: appRecord.grants
+		};
+	};
+	resolveLaunch = async (appReference, explicitDocumentGrantMap) => {
+		const sourceType = await this.detectLocalSourceType(appReference, false);
+		if (sourceType.kind === "directory") return {
+			appDirectory: sourceType.appDirectory,
+			documentGrantMap: explicitDocumentGrantMap
+		};
+		const appRecord = await this.registryService.getApp(appReference);
+		if (!appRecord) throw new Error(`未找到应用目录，也未找到已安装应用：${appReference}`);
+		const activeVersion = appRecord.installedVersions[appRecord.activeVersion];
+		if (!activeVersion) throw new Error(`已安装应用缺少激活版本：${appReference}`);
+		return {
+			appDirectory: activeVersion.installDirectory,
+			appId: appRecord.appId,
+			documentGrantMap: {
+				...appRecord.grants,
+				...explicitDocumentGrantMap
+			}
+		};
+	};
+	persistGrants = async (appId, documentGrantMap) => {
+		if (!appId || Object.keys(documentGrantMap).length === 0) return;
+		await this.registryService.updateGrants(appId, documentGrantMap);
+	};
+	resolveInstallSource = async (appSource, registryUrl) => {
+		const localSource = await this.detectLocalSourceType(appSource);
+		if (localSource.kind === "directory") return {
+			kind: "directory",
+			appDirectory: localSource.appDirectory,
+			sourceRef: localSource.appDirectory
+		};
+		if (localSource.kind === "bundle") return {
+			kind: "bundle",
+			bundlePath: localSource.bundlePath,
+			sourceRef: localSource.bundlePath
+		};
+		const registrySpec = this.parseRegistrySpec(appSource);
+		if (!registrySpec) {
+			if (this.looksLikePath(appSource)) throw new Error(`本地安装源不存在：${appSource}`);
+			throw new Error(`无法识别安装源：${appSource}`);
+		}
+		const registryResolution = await this.remoteRegistryClient.resolve({
+			appId: registrySpec.appId,
+			version: registrySpec.version,
+			registryUrl
+		});
+		return {
+			kind: "registry",
+			sourceRef: `${registryResolution.appId}@${registryResolution.version}`,
+			registryResolution
+		};
+	};
+	detectLocalSourceType = async (sourcePath, allowBundle = true) => {
+		const normalizedSource = path.resolve(sourcePath);
+		try {
+			await access(normalizedSource);
+			if ((await this.manifestService.load(normalizedSource)).appDirectory) return {
+				kind: "directory",
+				appDirectory: normalizedSource
+			};
+		} catch {
+			if (allowBundle && normalizedSource.endsWith(".napp")) try {
+				await access(normalizedSource);
+				return {
+					kind: "bundle",
+					bundlePath: normalizedSource
+				};
+			} catch {
+				return { kind: "missing" };
+			}
+			return { kind: "missing" };
+		}
+		return { kind: "missing" };
+	};
+	parseRegistrySpec = (appSource) => {
+		const match = /^(?<appId>[a-z0-9][a-z0-9._-]*)(?:@(?<version>[A-Za-z0-9._+-]+))?$/i.exec(appSource.trim());
+		if (!match?.groups?.appId) return;
+		return {
+			appId: match.groups.appId,
+			version: match.groups.version
+		};
+	};
+	looksLikePath = (appSource) => {
+		return appSource.startsWith(".") || appSource.startsWith("/") || appSource.includes(path.sep);
+	};
+};
+//#endregion
+export { AppInstallationService };

package/dist/install/app-installation.types.d.ts

@@ -0,0 +1,62 @@
+import { AppPermissions } from "../manifest/app-manifest.types.js";
+import { AppDocumentGrantMap } from "../permissions/app-permissions.types.js";
+import { AppPublisher } from "../registry/app-remote-registry.types.js";
+import { AppInstallSourceKind } from "../registry/app-registry.types.js";
+
+//#region src/install/app-installation.types.d.ts
+type AppInstallResult = {
+  appId: string;
+  name: string;
+  version: string;
+  installDirectory: string;
+  dataDirectory: string;
+  sourceKind: AppInstallSourceKind;
+  sourceRef: string;
+  permissions: AppPermissions;
+  registryUrl?: string;
+  bundleUrl?: string;
+  sha256?: string;
+  publisher?: AppPublisher;
+};
+type AppInfoResult = {
+  appId: string;
+  name: string;
+  description?: string;
+  activeVersion: string;
+  dataDirectory: string;
+  installedVersions: Array<{
+    version: string;
+    installDirectory: string;
+    sourceKind: AppInstallSourceKind;
+    sourceRef: string;
+    installedAt: string;
+    permissions: AppPermissions;
+    registryUrl?: string;
+    bundleUrl?: string;
+    sha256?: string;
+    publisher?: AppPublisher;
+  }>;
+  grants: AppDocumentGrantMap;
+};
+type InstalledAppListItem = {
+  appId: string;
+  name: string;
+  activeVersion: string;
+  sourceKind: AppInstallSourceKind;
+};
+type AppUninstallResult = {
+  appId: string;
+  removedVersions: string[];
+  dataRemoved: boolean;
+};
+type AppLaunchResolution = {
+  appDirectory: string;
+  appId?: string;
+  documentGrantMap: AppDocumentGrantMap;
+};
+type AppUpdateResult = AppInstallResult & {
+  previousVersion: string;
+  updated: boolean;
+};
+//#endregion
+export { AppInfoResult, AppInstallResult, AppLaunchResolution, AppUninstallResult, AppUpdateResult, InstalledAppListItem };