@nextclaw/app-runtime 0.2.0 → 0.3.0

package/dist/main.js

@@ -1,136 +1,9 @@
 #!/usr/bin/env node
-import { version } from "./package.js";
-import { CreateCommand } from "./commands/create.controller.js";
-import { RunCommand } from "./commands/run.controller.js";
-import { DevCommand } from "./commands/dev.controller.js";
-import { InspectCommand } from "./commands/inspect.controller.js";
+import { AppRuntimeCliService } from "./cli/app-runtime-cli.service.js";
 //#region src/main.ts
-var AppRuntimeCli = class {
-	run = async () => {
-		const [command, appDirectory, ...restArgs] = process.argv.slice(2);
-		if (command === "--help" || command === "help") {
-			this.writeUsage();
-			return;
-		}
-		if (command === "--version" || command === "version") {
-			this.write(`${version}\n`);
-			return;
-		}
-		if (!command || !appDirectory) {
-			this.writeUsage();
-			process.exit(1);
-		}
-		if (command === "create") {
-			const options = this.readCreateOptions(restArgs);
-			await new CreateCommand().run({
-				appDirectory,
-				json: options.json,
-				write: this.write
-			});
-			return;
-		}
-		const options = this.readRuntimeOptions(restArgs);
-		if (command === "inspect") {
-			await new InspectCommand().run({
-				appDirectory,
-				json: options.json,
-				write: this.write
-			});
-			return;
-		}
-		if (command === "run") {
-			await new RunCommand().run({
-				appDirectory,
-				host: options.host,
-				port: options.port,
-				json: options.json,
-				documentGrantMap: options.documentGrantMap,
-				write: this.write
-			});
-			return;
-		}
-		if (command === "dev") {
-			await new DevCommand().run({
-				appDirectory,
-				host: options.host,
-				port: options.port,
-				json: options.json,
-				documentGrantMap: options.documentGrantMap,
-				write: this.write
-			});
-			return;
-		}
-		this.writeUsage();
-		process.exit(1);
-	};
-	readCreateOptions = (rawArgs) => {
-		const options = { json: false };
-		for (const current of rawArgs) {
-			if (!current?.startsWith("--")) throw new Error(`未知参数：${current}`);
-			switch (current) {
-				case "--json":
-					options.json = true;
-					break;
-				default: throw new Error(`未知参数：${current}`);
-			}
-		}
-		return options;
-	};
-	readRuntimeOptions = (rawArgs) => {
-		const options = {
-			host: "127.0.0.1",
-			port: 3100,
-			json: false,
-			documentGrantMap: {}
-		};
-		for (let index = 0; index < rawArgs.length; index += 1) {
-			const current = rawArgs[index];
-			if (!current?.startsWith("--")) throw new Error(`未知参数：${current}`);
-			const nextValue = rawArgs[index + 1];
-			switch (current) {
-				case "--host":
-					options.host = this.requireOptionValue(current, nextValue);
-					index += 1;
-					break;
-				case "--port":
-					options.port = Number.parseInt(this.requireOptionValue(current, nextValue), 10);
-					if (Number.isNaN(options.port) || options.port < 0) throw new Error("--port 必须是非负整数。");
-					index += 1;
-					break;
-				case "--json":
-					options.json = true;
-					break;
-				case "--document":
-					this.assignDocumentGrant(options.documentGrantMap, this.requireOptionValue(current, nextValue));
-					index += 1;
-					break;
-				default: throw new Error(`未知参数：${current}`);
-			}
-		}
-		return options;
-	};
-	assignDocumentGrant = (documentGrantMap, rawGrant) => {
-		const delimiterIndex = rawGrant.indexOf("=");
-		if (delimiterIndex < 1) throw new Error("--document 必须使用 scopeId=/absolute/or/relative/path 格式。");
-		const scopeId = rawGrant.slice(0, delimiterIndex).trim();
-		const directoryPath = rawGrant.slice(delimiterIndex + 1).trim();
-		if (!scopeId || !directoryPath) throw new Error("--document 缺少 scopeId 或 path。");
-		documentGrantMap[scopeId] = directoryPath;
-	};
-	requireOptionValue = (flag, nextValue) => {
-		if (!nextValue || nextValue.startsWith("--")) throw new Error(`${flag} 缺少值。`);
-		return nextValue;
-	};
-	writeUsage = () => {
-		this.write("Usage: napp create <app-dir> [--json]\n");
-		this.write("       napp <inspect|run|dev> <app-dir> [--host 127.0.0.1] [--port 3100] [--json] [--document scope=/path]\n");
-		this.write("       napp --help\n");
-		this.write("       napp --version\n");
-	};
-	write = (text) => {
-		process.stdout.write(text);
-	};
-};
-new AppRuntimeCli().run();
+new AppRuntimeCliService().run().catch((error) => {
+	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+	process.exit(1);
+});
 //#endregion
 export {};

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.2.0";
+var version = "0.3.0";
 //#endregion
 export { version };

package/dist/paths/app-home.service.d.ts

@@ -0,0 +1,16 @@
+//#region src/paths/app-home.service.d.ts
+declare class AppHomeService {
+  private readonly appHomeDirectory;
+  constructor(appHomeDirectory?: string);
+  getAppHomeDirectory: () => string;
+  getPackagesDirectory: () => string;
+  getDataDirectory: () => string;
+  getRegistryPath: () => string;
+  getConfigPath: () => string;
+  getInstallDirectory: (appId: string, version: string) => string;
+  getAppDataDirectory: (appId: string) => string;
+  ensureBaseDirectories: () => Promise<void>;
+  createTemporaryDirectory: (prefix: string) => Promise<string>;
+}
+//#endregion
+export { AppHomeService };

package/dist/paths/app-home.service.js

@@ -0,0 +1,42 @@
+import { mkdir, mkdtemp } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+//#region src/paths/app-home.service.ts
+var AppHomeService = class {
+	constructor(appHomeDirectory = process.env.NEXTCLAW_APP_HOME ? path.resolve(process.env.NEXTCLAW_APP_HOME) : path.join(process.env.HOME ?? process.cwd(), ".nextclaw", "apps")) {
+		this.appHomeDirectory = appHomeDirectory;
+	}
+	getAppHomeDirectory = () => {
+		return this.appHomeDirectory;
+	};
+	getPackagesDirectory = () => {
+		return path.join(this.appHomeDirectory, "packages");
+	};
+	getDataDirectory = () => {
+		return path.join(this.appHomeDirectory, "data");
+	};
+	getRegistryPath = () => {
+		return path.join(this.appHomeDirectory, "registry.json");
+	};
+	getConfigPath = () => {
+		return path.join(this.appHomeDirectory, "config.json");
+	};
+	getInstallDirectory = (appId, version) => {
+		return path.join(this.getPackagesDirectory(), appId, version);
+	};
+	getAppDataDirectory = (appId) => {
+		return path.join(this.getDataDirectory(), appId);
+	};
+	ensureBaseDirectories = async () => {
+		await Promise.all([
+			mkdir(this.appHomeDirectory, { recursive: true }),
+			mkdir(this.getPackagesDirectory(), { recursive: true }),
+			mkdir(this.getDataDirectory(), { recursive: true })
+		]);
+	};
+	createTemporaryDirectory = async (prefix) => {
+		return mkdtemp(path.join(tmpdir(), prefix));
+	};
+};
+//#endregion
+export { AppHomeService };

package/dist/permissions/app-grant.service.d.ts

@@ -0,0 +1,22 @@
+import { AppManifestService } from "../manifest/app-manifest.service.js";
+import { AppDocumentGrantMutationResult, AppInstalledPermissionState } from "./app-permissions.types.js";
+import { AppRegistryService } from "../registry/app-registry.service.js";
+
+//#region src/permissions/app-grant.service.d.ts
+declare class AppGrantService {
+  private readonly registryService;
+  private readonly manifestService;
+  constructor(registryService?: AppRegistryService, manifestService?: AppManifestService);
+  summarize: (appId: string) => Promise<AppInstalledPermissionState>;
+  grantDocumentScope: (params: {
+    appId: string;
+    scopeId: string;
+    directoryPath: string;
+  }) => Promise<AppDocumentGrantMutationResult>;
+  revokeDocumentScope: (params: {
+    appId: string;
+    scopeId: string;
+  }) => Promise<AppDocumentGrantMutationResult>;
+}
+//#endregion
+export { AppGrantService };

package/dist/permissions/app-grant.service.js

@@ -0,0 +1,63 @@
+import { AppManifestService } from "../manifest/app-manifest.service.js";
+import { AppRegistryService } from "../registry/app-registry.service.js";
+import { access } from "node:fs/promises";
+import path from "node:path";
+//#region src/permissions/app-grant.service.ts
+var AppGrantService = class {
+	constructor(registryService = new AppRegistryService(), manifestService = new AppManifestService()) {
+		this.registryService = registryService;
+		this.manifestService = manifestService;
+	}
+	summarize = async (appId) => {
+		const appRecord = await this.registryService.getApp(appId);
+		if (!appRecord) throw new Error(`未找到已安装应用：${appId}`);
+		const activeVersion = appRecord.installedVersions[appRecord.activeVersion];
+		if (!activeVersion) throw new Error(`已安装应用缺少激活版本：${appId}`);
+		const requestedPermissions = (await this.manifestService.load(activeVersion.installDirectory)).manifest.permissions ?? {};
+		return {
+			appId: appRecord.appId,
+			name: appRecord.name,
+			activeVersion: appRecord.activeVersion,
+			documentAccess: (requestedPermissions.documentAccess ?? []).map((scope) => ({
+				id: scope.id,
+				mode: scope.mode,
+				description: scope.description,
+				granted: Boolean(appRecord.grants[scope.id]),
+				grantedPath: appRecord.grants[scope.id]
+			})),
+			allowedDomains: requestedPermissions.allowedDomains ?? [],
+			storage: {
+				enabled: requestedPermissions.storage !== void 0 && requestedPermissions.storage !== false,
+				namespace: typeof requestedPermissions.storage === "object" ? requestedPermissions.storage.namespace : void 0
+			},
+			capabilities: { hostBridge: requestedPermissions.capabilities?.hostBridge !== false }
+		};
+	};
+	grantDocumentScope = async (params) => {
+		const { appId, scopeId, directoryPath } = params;
+		if (!(await this.summarize(appId)).documentAccess.find((scope) => scope.id === scopeId)) throw new Error(`应用 ${appId} 未声明 documentAccess scope：${scopeId}`);
+		const normalizedDirectory = path.resolve(directoryPath);
+		try {
+			await access(normalizedDirectory);
+		} catch {
+			throw new Error(`授权目录不存在：${normalizedDirectory}`);
+		}
+		await this.registryService.setDocumentGrant(appId, scopeId, normalizedDirectory);
+		return {
+			appId,
+			scopeId,
+			grantedPath: normalizedDirectory
+		};
+	};
+	revokeDocumentScope = async (params) => {
+		const { appId, scopeId } = params;
+		await this.summarize(appId);
+		return {
+			appId,
+			scopeId,
+			removed: await this.registryService.removeDocumentGrant(appId, scopeId)
+		};
+	};
+};
+//#endregion
+export { AppGrantService };

package/dist/permissions/app-permissions.service.d.ts

@@ -3,7 +3,9 @@ import { AppDocumentGrantMap, AppPermissionSummary, ResolvedPermissions } from "
 
 //#region src/permissions/app-permissions.service.d.ts
 declare class AppPermissionsService {
-  resolve: (bundle: AppManifestBundle, documentGrantMap: AppDocumentGrantMap) => Promise<ResolvedPermissions>;
+  resolve: (bundle: AppManifestBundle, documentGrantMap: AppDocumentGrantMap, context?: {
+    appId?: string;
+  }) => Promise<ResolvedPermissions>;
   summarize: (bundle: AppManifestBundle, permissions: ResolvedPermissions) => AppPermissionSummary;
   private resolveDocumentGrant;
 }

package/dist/permissions/app-permissions.service.js

@@ -2,10 +2,10 @@ import { access } from "node:fs/promises";
 import path from "node:path";
 //#region src/permissions/app-permissions.service.ts
 var AppPermissionsService = class {
-	resolve = async (bundle, documentGrantMap) => {
+	resolve = async (bundle, documentGrantMap, context) => {
 		const requestedPermissions = bundle.manifest.permissions ?? {};
 		return {
-			documentAccess: requestedPermissions.documentAccess === void 0 ? [] : await Promise.all(requestedPermissions.documentAccess.map((scope) => this.resolveDocumentGrant(scope, documentGrantMap))),
+			documentAccess: requestedPermissions.documentAccess === void 0 ? [] : await Promise.all(requestedPermissions.documentAccess.map((scope) => this.resolveDocumentGrant(scope, documentGrantMap, context?.appId))),
 			allowedDomains: requestedPermissions.allowedDomains ?? [],
 			storage: {
 				enabled: requestedPermissions.storage !== void 0 && requestedPermissions.storage !== false,
@@ -23,11 +23,18 @@ var AppPermissionsService = class {
 			capabilities: permissions.capabilities
 		};
 	};
-	resolveDocumentGrant = async (scope, documentGrantMap) => {
+	resolveDocumentGrant = async (scope, documentGrantMap, appId) => {
 		const grantedPath = documentGrantMap[scope.id];
-		if (!grantedPath) throw new Error(`缺少 documentAccess 授权：${scope.id}`);
+		if (!grantedPath) {
+			if (appId) throw new Error(`缺少 documentAccess 授权：${scope.id}。请先执行 napp grant ${appId} --document ${scope.id}=/absolute/path`);
+			throw new Error(`缺少 documentAccess 授权：${scope.id}。请通过 --document ${scope.id}=/absolute/path 提供授权。`);
+		}
 		const normalizedPath = path.resolve(grantedPath);
-		await access(normalizedPath);
+		try {
+			await access(normalizedPath);
+		} catch {
+			throw new Error(`documentAccess 授权路径不存在：${scope.id} -> ${normalizedPath}`);
+		}
 		return {
 			id: scope.id,
 			mode: scope.mode,

package/dist/permissions/app-permissions.types.d.ts

@@ -22,5 +22,32 @@ type ResolvedPermissions = {
 type AppPermissionSummary = Pick<ResolvedPermissions, "documentAccess" | "allowedDomains" | "storage" | "capabilities"> & {
   requested: AppPermissions;
 };
+type AppDocumentGrantState = {
+  id: string;
+  mode: "read" | "read-write";
+  description?: string;
+  granted: boolean;
+  grantedPath?: string;
+};
+type AppInstalledPermissionState = {
+  appId: string;
+  name: string;
+  activeVersion: string;
+  documentAccess: AppDocumentGrantState[];
+  allowedDomains: string[];
+  storage: {
+    enabled: boolean;
+    namespace?: string;
+  };
+  capabilities: {
+    hostBridge: boolean;
+  };
+};
+type AppDocumentGrantMutationResult = {
+  appId: string;
+  scopeId: string;
+  grantedPath?: string;
+  removed?: boolean;
+};
 //#endregion
-export { AppDocumentGrantMap, AppPermissionSummary, ResolvedDocumentGrant, ResolvedPermissions };
+export { AppDocumentGrantMap, AppDocumentGrantMutationResult, AppDocumentGrantState, AppInstalledPermissionState, AppPermissionSummary, ResolvedDocumentGrant, ResolvedPermissions };

package/dist/registry/app-registry-config.service.d.ts

@@ -0,0 +1,16 @@
+import { AppHomeService } from "../paths/app-home.service.js";
+import { AppRegistryConfigSnapshot } from "./app-remote-registry.types.js";
+
+//#region src/registry/app-registry-config.service.d.ts
+declare class AppRegistryConfigService {
+  private readonly appHomeService;
+  constructor(appHomeService?: AppHomeService);
+  getSnapshot: () => Promise<AppRegistryConfigSnapshot>;
+  setRegistryUrl: (registryUrl: string) => Promise<AppRegistryConfigSnapshot>;
+  resetRegistryUrl: () => Promise<AppRegistryConfigSnapshot>;
+  private loadOptionalConfig;
+  private parseConfig;
+  private normalizeRegistryUrl;
+}
+//#endregion
+export { AppRegistryConfigService };

package/dist/registry/app-registry-config.service.js

@@ -0,0 +1,84 @@
+import { AppHomeService } from "../paths/app-home.service.js";
+import { DEFAULT_APP_REGISTRY_URL } from "./app-remote-registry.types.js";
+import { readFile, rm, writeFile } from "node:fs/promises";
+//#region src/registry/app-registry-config.service.ts
+var AppRegistryConfigService = class {
+	constructor(appHomeService = new AppHomeService()) {
+		this.appHomeService = appHomeService;
+	}
+	getSnapshot = async () => {
+		const envUrl = process.env.NEXTCLAW_APP_REGISTRY?.trim();
+		if (envUrl) return {
+			defaultUrl: DEFAULT_APP_REGISTRY_URL,
+			currentUrl: this.normalizeRegistryUrl(envUrl),
+			source: "env"
+		};
+		const config = await this.loadOptionalConfig();
+		if (config) return {
+			defaultUrl: DEFAULT_APP_REGISTRY_URL,
+			currentUrl: this.normalizeRegistryUrl(config.registry.url),
+			source: "config"
+		};
+		return {
+			defaultUrl: DEFAULT_APP_REGISTRY_URL,
+			currentUrl: DEFAULT_APP_REGISTRY_URL,
+			source: "default"
+		};
+	};
+	setRegistryUrl = async (registryUrl) => {
+		const normalized = this.normalizeRegistryUrl(registryUrl);
+		await this.appHomeService.ensureBaseDirectories();
+		await writeFile(this.appHomeService.getConfigPath(), `${JSON.stringify({
+			schemaVersion: 1,
+			registry: { url: normalized }
+		}, null, 2)}\n`, "utf-8");
+		return {
+			defaultUrl: DEFAULT_APP_REGISTRY_URL,
+			currentUrl: normalized,
+			source: "config"
+		};
+	};
+	resetRegistryUrl = async () => {
+		await rm(this.appHomeService.getConfigPath(), { force: true });
+		return {
+			defaultUrl: DEFAULT_APP_REGISTRY_URL,
+			currentUrl: DEFAULT_APP_REGISTRY_URL,
+			source: "default"
+		};
+	};
+	loadOptionalConfig = async () => {
+		try {
+			const raw = await readFile(this.appHomeService.getConfigPath(), "utf-8");
+			return this.parseConfig(JSON.parse(raw));
+		} catch (error) {
+			if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") return;
+			throw error;
+		}
+	};
+	parseConfig = (rawConfig) => {
+		if (!rawConfig || typeof rawConfig !== "object" || Array.isArray(rawConfig)) throw new Error("config.json 必须是对象。");
+		const candidate = rawConfig;
+		if (candidate.schemaVersion !== 1) throw new Error("当前只支持 config schemaVersion = 1。");
+		const registry = candidate.registry;
+		if (!registry || typeof registry !== "object" || Array.isArray(registry)) throw new Error("config.registry 必须是对象。");
+		const registryUrl = registry.url;
+		if (typeof registryUrl !== "string" || !registryUrl.trim()) throw new Error("config.registry.url 必须是非空字符串。");
+		return {
+			schemaVersion: 1,
+			registry: { url: this.normalizeRegistryUrl(registryUrl) }
+		};
+	};
+	normalizeRegistryUrl = (registryUrl) => {
+		let normalized;
+		try {
+			normalized = new URL(registryUrl);
+		} catch {
+			throw new Error(`非法 registry URL：${registryUrl}`);
+		}
+		if (normalized.protocol !== "http:" && normalized.protocol !== "https:") throw new Error(`registry URL 只支持 http/https：${registryUrl}`);
+		const text = normalized.toString();
+		return text.endsWith("/") ? text : `${text}/`;
+	};
+};
+//#endregion
+export { AppRegistryConfigService };

package/dist/registry/app-registry.service.d.ts

@@ -0,0 +1,38 @@
+import { AppPermissions } from "../manifest/app-manifest.types.js";
+import { AppDocumentGrantMap } from "../permissions/app-permissions.types.js";
+import { AppHomeService } from "../paths/app-home.service.js";
+import { AppInstallSourceKind, AppRegistry, AppRegistryAppRecord, AppRegistryInstalledVersion } from "./app-registry.types.js";
+
+//#region src/registry/app-registry.service.d.ts
+declare class AppRegistryService {
+  private readonly appHomeService;
+  constructor(appHomeService?: AppHomeService);
+  load: () => Promise<AppRegistry>;
+  save: (registry: AppRegistry) => Promise<void>;
+  listApps: () => Promise<AppRegistryAppRecord[]>;
+  getApp: (appId: string) => Promise<AppRegistryAppRecord | undefined>;
+  getActiveVersion: (appId: string) => Promise<AppRegistryInstalledVersion | undefined>;
+  upsertInstallation: (params: {
+    appId: string;
+    name: string;
+    description?: string;
+    version: string;
+    installDirectory: string;
+    dataDirectory: string;
+    sourceKind: AppInstallSourceKind;
+    sourceRef: string;
+    installedAt: string;
+    permissions: AppPermissions;
+    registryUrl?: string;
+    bundleUrl?: string;
+    sha256?: string;
+    publisher?: AppRegistryInstalledVersion["publisher"];
+  }) => Promise<AppRegistryAppRecord>;
+  updateGrants: (appId: string, grants: AppDocumentGrantMap) => Promise<AppRegistryAppRecord>;
+  setDocumentGrant: (appId: string, scopeId: string, directoryPath: string) => Promise<AppRegistryAppRecord>;
+  removeDocumentGrant: (appId: string, scopeId: string) => Promise<boolean>;
+  removeApp: (appId: string) => Promise<AppRegistryAppRecord | undefined>;
+  private parseRegistry;
+}
+//#endregion
+export { AppRegistryService };

package/dist/registry/app-registry.service.js

@@ -0,0 +1,115 @@
+import { AppHomeService } from "../paths/app-home.service.js";
+import { readFile, writeFile } from "node:fs/promises";
+//#region src/registry/app-registry.service.ts
+var AppRegistryService = class {
+	constructor(appHomeService = new AppHomeService()) {
+		this.appHomeService = appHomeService;
+	}
+	load = async () => {
+		await this.appHomeService.ensureBaseDirectories();
+		const registryPath = this.appHomeService.getRegistryPath();
+		try {
+			const raw = await readFile(registryPath, "utf-8");
+			return this.parseRegistry(JSON.parse(raw));
+		} catch (error) {
+			if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") return {
+				schemaVersion: 1,
+				apps: {}
+			};
+			throw error;
+		}
+	};
+	save = async (registry) => {
+		await this.appHomeService.ensureBaseDirectories();
+		await writeFile(this.appHomeService.getRegistryPath(), `${JSON.stringify(registry, null, 2)}\n`, "utf-8");
+	};
+	listApps = async () => {
+		const registry = await this.load();
+		return Object.values(registry.apps).sort((left, right) => left.appId.localeCompare(right.appId));
+	};
+	getApp = async (appId) => {
+		return (await this.load()).apps[appId];
+	};
+	getActiveVersion = async (appId) => {
+		const appRecord = await this.getApp(appId);
+		if (!appRecord) return;
+		return appRecord.installedVersions[appRecord.activeVersion];
+	};
+	upsertInstallation = async (params) => {
+		const { appId, name, description, version, installDirectory, dataDirectory, sourceKind, sourceRef, installedAt, permissions, registryUrl, bundleUrl, sha256, publisher } = params;
+		const registry = await this.load();
+		const currentRecord = registry.apps[appId];
+		const nextRecord = {
+			appId,
+			name,
+			description,
+			activeVersion: version,
+			dataDirectory,
+			installedVersions: {
+				...currentRecord?.installedVersions ?? {},
+				[version]: {
+					version,
+					installDirectory,
+					sourceKind,
+					sourceRef,
+					installedAt,
+					permissions,
+					registryUrl,
+					bundleUrl,
+					sha256,
+					publisher
+				}
+			},
+			grants: currentRecord?.grants ?? {}
+		};
+		registry.apps[appId] = nextRecord;
+		await this.save(registry);
+		return nextRecord;
+	};
+	updateGrants = async (appId, grants) => {
+		const registry = await this.load();
+		const appRecord = registry.apps[appId];
+		if (!appRecord) throw new Error(`未找到已安装应用：${appId}`);
+		appRecord.grants = {
+			...appRecord.grants,
+			...grants
+		};
+		registry.apps[appId] = appRecord;
+		await this.save(registry);
+		return appRecord;
+	};
+	setDocumentGrant = async (appId, scopeId, directoryPath) => {
+		return this.updateGrants(appId, { [scopeId]: directoryPath });
+	};
+	removeDocumentGrant = async (appId, scopeId) => {
+		const registry = await this.load();
+		const appRecord = registry.apps[appId];
+		if (!appRecord) throw new Error(`未找到已安装应用：${appId}`);
+		if (!(scopeId in appRecord.grants)) return false;
+		delete appRecord.grants[scopeId];
+		registry.apps[appId] = appRecord;
+		await this.save(registry);
+		return true;
+	};
+	removeApp = async (appId) => {
+		const registry = await this.load();
+		const appRecord = registry.apps[appId];
+		if (!appRecord) return;
+		delete registry.apps[appId];
+		await this.save(registry);
+		return appRecord;
+	};
+	parseRegistry = (rawRegistry) => {
+		if (!rawRegistry || typeof rawRegistry !== "object" || Array.isArray(rawRegistry)) throw new Error("registry.json 必须是对象。");
+		const candidate = rawRegistry;
+		if (candidate.schemaVersion !== 1) throw new Error("当前只支持 registry schemaVersion = 1。");
+		const apps = candidate.apps;
+		if (!apps || typeof apps !== "object" || Array.isArray(apps)) throw new Error("registry.apps 必须是对象。");
+		return {
+			schemaVersion: 1,
+			apps
+		};
+	};
+};
+//#endregion
+export { AppRegistryService };

package/dist/registry/app-registry.types.d.ts

@@ -0,0 +1,33 @@
+import { AppPermissions } from "../manifest/app-manifest.types.js";
+import { AppDocumentGrantMap } from "../permissions/app-permissions.types.js";
+import { AppPublisher } from "./app-remote-registry.types.js";
+
+//#region src/registry/app-registry.types.d.ts
+type AppInstallSourceKind = "bundle" | "directory" | "registry";
+type AppRegistryInstalledVersion = {
+  version: string;
+  installDirectory: string;
+  sourceKind: AppInstallSourceKind;
+  sourceRef: string;
+  installedAt: string;
+  permissions: AppPermissions;
+  registryUrl?: string;
+  bundleUrl?: string;
+  sha256?: string;
+  publisher?: AppPublisher;
+};
+type AppRegistryAppRecord = {
+  appId: string;
+  name: string;
+  description?: string;
+  activeVersion: string;
+  dataDirectory: string;
+  installedVersions: Record<string, AppRegistryInstalledVersion>;
+  grants: AppDocumentGrantMap;
+};
+type AppRegistry = {
+  schemaVersion: 1;
+  apps: Record<string, AppRegistryAppRecord>;
+};
+//#endregion
+export { AppInstallSourceKind, AppRegistry, AppRegistryAppRecord, AppRegistryInstalledVersion };