@nextclaw/app-runtime 0.1.0 → 0.3.0

package/README.md

@@ -2,11 +2,22 @@
 
 `@nextclaw/app-runtime` 是一个独立的微应用 runtime/CLI 包。
 
-当前 MVP 提供三件事：
+当前相对完善 MVP 提供下面这些能力：
 
+- `napp create <app-dir>`：生成一个最小可跑的微应用骨架
 - `napp inspect <app-dir>`：校验应用目录与 manifest
-- `napp run <app-dir>`：启动本地宿主，提供 UI 静态服务和桥接 API
+- `napp run <app-dir|app-id>`：启动本地宿主，支持目录运行和已安装应用运行
 - `napp dev <app-dir>`：当前等价于 `run`
+- `napp pack <app-dir>`：把应用目录打成 `.napp` bundle
+- `napp install <app-dir|bundle.napp|app-id[@version]>`：从本地或 registry 安装应用
+- `napp update <app-id>`：更新已安装应用
+- `napp uninstall <app-id>`：卸载已安装应用
+- `napp list`：列出已安装应用
+- `napp info <app-id>`：查看已安装应用详情
+- `napp registry [get|set|reset]`：查看或切换 registry
+- `napp permissions <app-id>`：查看应用权限状态
+- `napp grant <app-id> --document scope=/path`：写入目录授权
+- `napp revoke <app-id> --document scope`：撤销目录授权
 
 ## 安装
 
@@ -21,7 +32,7 @@ napp --help
 napp --version
 ```
 
-第一版先聚焦“独立可运行的微应用宿主”，不接入现有 NextClaw 主产品路由、服务或传播层。
+第一版先聚焦“独立可运行的微应用宿主 + 可分发、可安装、可更新、可授权的 CLI/runtime 闭环”，不接入现有 NextClaw 主产品路由、服务或 GUI app store。
 
 ## 应用目录
 
@@ -41,10 +52,121 @@ assets/
 - 宿主桥接：`/__napp/*`
 - 权限词汇：`documentAccess`、`allowedDomains`、`storage`、`capabilities`
 - 当前 Wasm 执行底座：Node 原生 `WebAssembly`
+- 分发包形态：`.napp`（底层为 zip）
+- 安装目录：`~/.nextclaw/apps/packages/<app-id>/<version>/`
+- 用户数据目录：`~/.nextclaw/apps/data/<app-id>/`
+- 本地 registry：`~/.nextclaw/apps/registry.json`
+- 本地 config：`~/.nextclaw/apps/config.json`
+- 默认 registry：`https://registry.nextclaw.com/`
+
+## 当前 MVP 工作流
+
+开发者工作流：
+
+```bash
+napp create ./my-first-napp
+napp inspect ./my-first-napp
+napp pack ./my-first-napp
+```
+
+本地安装工作流：
+
+```bash
+napp install ./my-first-napp
+napp list
+napp info nextclaw.my-first-napp
+napp run nextclaw.my-first-napp
+```
+
+registry 安装与更新工作流：
+
+```bash
+napp registry set https://registry.example.com/
+napp install nextclaw.hello-notes
+napp permissions nextclaw.hello-notes
+napp grant nextclaw.hello-notes --document notes=/absolute/path/to/notes
+napp run nextclaw.hello-notes
+napp update nextclaw.hello-notes
+```
+
+卸载与权限回收：
+
+```bash
+napp revoke nextclaw.my-first-napp --document notes
+napp uninstall nextclaw.my-first-napp
+napp uninstall nextclaw.my-first-napp --purge-data
+```
 
 ## 示例
 
+```bash
+napp create ./my-first-napp
+napp inspect ./my-first-napp
+napp pack ./my-first-napp
+napp install ./my-first-napp
+napp list
+napp info nextclaw.my-first-napp
+napp permissions nextclaw.my-first-napp
+napp run nextclaw.my-first-napp
+```
+
+已有示例应用：
+
 ```bash
 napp inspect ./apps/examples/hello-notes
+napp pack ./apps/examples/hello-notes
+napp install ./apps/examples/hello-notes
+napp grant nextclaw.hello-notes --document notes=/absolute/path/to/notes
 napp run ./apps/examples/hello-notes --document notes=/absolute/path/to/notes
 ```
+
+registry 示例：
+
+```bash
+napp registry get
+napp registry set https://registry.example.com/
+napp install nextclaw.hello-notes
+napp update nextclaw.hello-notes
+```
+
+## Bundle 结构
+
+`.napp` bundle 的最小结构如下：
+
+```text
+manifest.json
+main/
+ui/
+assets/
+.napp/
+  bundle.json
+  checksums.json
+```
+
+## Registry Metadata 结构
+
+registry 按 npm 风格使用一个 base URL，再按 app id 拉取 metadata 文档。metadata 的最小结构如下：
+
+```json
+{
+  "name": "nextclaw.hello-notes",
+  "description": "Registry-hosted Hello Notes",
+  "dist-tags": {
+    "latest": "0.2.0"
+  },
+  "versions": {
+    "0.2.0": {
+      "name": "nextclaw.hello-notes",
+      "version": "0.2.0",
+      "publisher": {
+        "id": "nextclaw",
+        "name": "NextClaw Official"
+      },
+      "dist": {
+        "bundle": "./-/hello-notes-0.2.0.napp",
+        "sha256": "<sha256>"
+      }
+    }
+  }
+}
+```

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

@@ -0,0 +1,27 @@
+import { AppManifestService } from "../manifest/app-manifest.service.js";
+import { AppBundleExtractResult, AppBundlePackResult } from "./app-bundle.types.js";
+
+//#region src/bundle/app-bundle.service.d.ts
+declare class AppBundleService {
+  private readonly manifestService;
+  constructor(manifestService?: AppManifestService);
+  packAppDirectory: (params: {
+    appDirectory: string;
+    outputPath?: string;
+  }) => Promise<AppBundlePackResult>;
+  extractBundle: (params: {
+    bundlePath: string;
+    targetDirectory: string;
+  }) => Promise<AppBundleExtractResult>;
+  private collectAppFiles;
+  private collectDirectoryPaths;
+  private buildMetadata;
+  private buildChecksums;
+  private computeSha256;
+  private normalizeBundleFileName;
+  private normalizeArchiveEntry;
+  private readJsonFile;
+  private verifyChecksums;
+}
+//#endregion
+export { AppBundleService };

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

@@ -0,0 +1,133 @@
+import { AppManifestService } from "../manifest/app-manifest.service.js";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { strToU8, unzipSync, zipSync } from "fflate";
+//#region src/bundle/app-bundle.service.ts
+var AppBundleService = class {
+	constructor(manifestService = new AppManifestService()) {
+		this.manifestService = manifestService;
+	}
+	packAppDirectory = async (params) => {
+		const bundle = await this.manifestService.load(params.appDirectory);
+		const appFiles = await this.collectAppFiles(bundle.appDirectory);
+		const metadata = this.buildMetadata(bundle.manifest.id, bundle.manifest.name, bundle.manifest.version);
+		const bundleJsonPath = ".napp/bundle.json";
+		const checksumsJsonPath = ".napp/checksums.json";
+		const bundleJsonBytes = strToU8(`${JSON.stringify(metadata, null, 2)}\n`);
+		const checksums = this.buildChecksums({
+			...appFiles,
+			[bundleJsonPath]: bundleJsonBytes
+		});
+		const checksumsJsonBytes = strToU8(`${JSON.stringify(checksums, null, 2)}\n`);
+		const archiveBytes = zipSync({
+			...appFiles,
+			[bundleJsonPath]: bundleJsonBytes,
+			[checksumsJsonPath]: checksumsJsonBytes
+		}, { level: 9 });
+		const outputPath = params.outputPath ? path.resolve(params.outputPath) : path.join(path.dirname(bundle.appDirectory), `${this.normalizeBundleFileName(bundle.manifest.id)}-${bundle.manifest.version}.napp`);
+		await mkdir(path.dirname(outputPath), { recursive: true });
+		await writeFile(outputPath, Buffer.from(archiveBytes));
+		return {
+			bundlePath: outputPath,
+			metadata
+		};
+	};
+	extractBundle = async (params) => {
+		const bundlePath = path.resolve(params.bundlePath);
+		const targetDirectory = path.resolve(params.targetDirectory);
+		await rm(targetDirectory, {
+			recursive: true,
+			force: true
+		});
+		await mkdir(targetDirectory, { recursive: true });
+		const archive = unzipSync(new Uint8Array(await readFile(bundlePath)));
+		const entryNames = Object.keys(archive).sort((left, right) => left.localeCompare(right));
+		for (const entryName of entryNames) {
+			const normalizedEntry = this.normalizeArchiveEntry(entryName);
+			const targetPath = path.join(targetDirectory, normalizedEntry);
+			await mkdir(path.dirname(targetPath), { recursive: true });
+			await writeFile(targetPath, Buffer.from(archive[entryName]));
+		}
+		const metadata = await this.readJsonFile(path.join(targetDirectory, ".napp", "bundle.json"), "bundle metadata");
+		const checksums = await this.readJsonFile(path.join(targetDirectory, ".napp", "checksums.json"), "bundle checksums");
+		await this.verifyChecksums(targetDirectory, checksums);
+		await this.manifestService.load(targetDirectory);
+		return {
+			appDirectory: targetDirectory,
+			metadata,
+			checksums
+		};
+	};
+	collectAppFiles = async (appDirectory) => {
+		const filePaths = new Set(["manifest.json"]);
+		await this.collectDirectoryPaths(path.join(appDirectory, "main"), appDirectory, filePaths);
+		await this.collectDirectoryPaths(path.join(appDirectory, "ui"), appDirectory, filePaths);
+		await this.collectDirectoryPaths(path.join(appDirectory, "assets"), appDirectory, filePaths);
+		const sortedPaths = Array.from(filePaths).sort((left, right) => left.localeCompare(right));
+		const appFiles = {};
+		for (const relativePath of sortedPaths) appFiles[relativePath] = new Uint8Array(await readFile(path.join(appDirectory, relativePath)));
+		return appFiles;
+	};
+	collectDirectoryPaths = async (directoryPath, appDirectory, filePaths) => {
+		try {
+			const entries = await readdir(directoryPath, { withFileTypes: true });
+			for (const entry of entries) {
+				const entryPath = path.join(directoryPath, entry.name);
+				if (entry.isDirectory()) {
+					await this.collectDirectoryPaths(entryPath, appDirectory, filePaths);
+					continue;
+				}
+				if (!entry.isFile()) continue;
+				filePaths.add(path.relative(appDirectory, entryPath));
+			}
+		} catch {
+			return;
+		}
+	};
+	buildMetadata = (appId, name, version) => {
+		return {
+			bundleFormatVersion: 1,
+			appId,
+			name,
+			version,
+			entryManifest: "manifest.json",
+			checksumsFile: ".napp/checksums.json"
+		};
+	};
+	buildChecksums = (files) => {
+		const entries = Object.entries(files).sort(([left], [right]) => left.localeCompare(right));
+		return {
+			algorithm: "sha256",
+			files: Object.fromEntries(entries.map(([relativePath, fileBytes]) => [relativePath, this.computeSha256(fileBytes)]))
+		};
+	};
+	computeSha256 = (fileBytes) => {
+		return createHash("sha256").update(Buffer.from(fileBytes)).digest("hex");
+	};
+	normalizeBundleFileName = (appId) => {
+		return appId.replace(/[^a-zA-Z0-9._-]+/g, "-");
+	};
+	normalizeArchiveEntry = (entryName) => {
+		const normalized = entryName.replace(/\\/g, "/");
+		if (!normalized || normalized.startsWith("/") || normalized.includes("../")) throw new Error(`bundle 内包含非法路径：${entryName}`);
+		return normalized;
+	};
+	readJsonFile = async (filePath, label) => {
+		try {
+			return JSON.parse(await readFile(filePath, "utf-8"));
+		} catch (error) {
+			throw new Error(`无法读取 ${label}：${error instanceof Error ? error.message : String(error)}`);
+		}
+	};
+	verifyChecksums = async (appDirectory, checksums) => {
+		if (checksums.algorithm !== "sha256") throw new Error("当前只支持 sha256 checksums。");
+		const entries = Object.entries(checksums.files).sort(([left], [right]) => left.localeCompare(right));
+		for (const [relativePath, expectedHash] of entries) {
+			const fileBytes = new Uint8Array(await readFile(path.join(appDirectory, relativePath)));
+			if (this.computeSha256(fileBytes) !== expectedHash) throw new Error(`bundle checksum 校验失败：${relativePath}`);
+		}
+	};
+};
+//#endregion
+export { AppBundleService };

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

@@ -0,0 +1,24 @@
+//#region src/bundle/app-bundle.types.d.ts
+type AppBundleMetadata = {
+  bundleFormatVersion: 1;
+  appId: string;
+  name: string;
+  version: string;
+  entryManifest: "manifest.json";
+  checksumsFile: ".napp/checksums.json";
+};
+type AppBundleChecksums = {
+  algorithm: "sha256";
+  files: Record<string, string>;
+};
+type AppBundlePackResult = {
+  bundlePath: string;
+  metadata: AppBundleMetadata;
+};
+type AppBundleExtractResult = {
+  appDirectory: string;
+  metadata: AppBundleMetadata;
+  checksums: AppBundleChecksums;
+};
+//#endregion
+export { AppBundleChecksums, AppBundleExtractResult, AppBundleMetadata, AppBundlePackResult };

package/dist/cli/app-runtime-cli.service.d.ts

@@ -0,0 +1,27 @@
+import { AppRuntimeOptionsService } from "./app-runtime-options.service.js";
+
+//#region src/cli/app-runtime-cli.service.d.ts
+declare class AppRuntimeCliService {
+  private readonly optionsService;
+  constructor(optionsService?: AppRuntimeOptionsService);
+  run: () => Promise<void>;
+  private dispatch;
+  private handleCreate;
+  private handleInspect;
+  private handleRun;
+  private handleDev;
+  private handlePack;
+  private handleInstall;
+  private handleUpdate;
+  private handleUninstall;
+  private handleList;
+  private handleInfo;
+  private handleRegistry;
+  private handlePermissions;
+  private handleGrant;
+  private handleRevoke;
+  private writeUsage;
+  private write;
+}
+//#endregion
+export { AppRuntimeCliService };

package/dist/cli/app-runtime-cli.service.js

@@ -0,0 +1,281 @@
+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 { GrantCommand } from "../commands/grant.controller.js";
+import { InfoCommand } from "../commands/info.controller.js";
+import { InspectCommand } from "../commands/inspect.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 "./app-runtime-options.service.js";
+//#region src/cli/app-runtime-cli.service.ts
+var AppRuntimeCliService = class {
+	constructor(optionsService = new AppRuntimeOptionsService()) {
+		this.optionsService = optionsService;
+	}
+	run = async () => {
+		const [command, ...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) {
+			this.writeUsage();
+			process.exit(1);
+		}
+		await this.dispatch(command, restArgs);
+	};
+	dispatch = async (command, restArgs) => {
+		switch (command) {
+			case "create":
+				await this.handleCreate(restArgs);
+				return;
+			case "inspect":
+				await this.handleInspect(restArgs);
+				return;
+			case "run":
+				await this.handleRun(restArgs);
+				return;
+			case "dev":
+				await this.handleDev(restArgs);
+				return;
+			case "pack":
+				await this.handlePack(restArgs);
+				return;
+			case "install":
+				await this.handleInstall(restArgs);
+				return;
+			case "update":
+				await this.handleUpdate(restArgs);
+				return;
+			case "uninstall":
+				await this.handleUninstall(restArgs);
+				return;
+			case "list":
+				await this.handleList(restArgs);
+				return;
+			case "info":
+				await this.handleInfo(restArgs);
+				return;
+			case "registry":
+				await this.handleRegistry(restArgs);
+				return;
+			case "permissions":
+				await this.handlePermissions(restArgs);
+				return;
+			case "grant":
+				await this.handleGrant(restArgs);
+				return;
+			case "revoke":
+				await this.handleRevoke(restArgs);
+				return;
+			default:
+				this.writeUsage();
+				process.exit(1);
+		}
+	};
+	handleCreate = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("create", restArgs);
+		const options = this.optionsService.readCreateOptions(optionArgs);
+		await new CreateCommand().run({
+			appDirectory: target,
+			json: options.json,
+			write: this.write
+		});
+	};
+	handleInspect = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("inspect", restArgs);
+		const options = this.optionsService.readJsonOnlyOptions(optionArgs);
+		await new InspectCommand().run({
+			appDirectory: target,
+			json: options.json,
+			write: this.write
+		});
+	};
+	handleRun = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("run", restArgs);
+		const options = this.optionsService.readRuntimeOptions(optionArgs);
+		await new RunCommand().run({
+			appReference: target,
+			host: options.host,
+			port: options.port,
+			json: options.json,
+			documentGrantMap: options.documentGrantMap,
+			write: this.write
+		});
+	};
+	handleDev = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("dev", restArgs);
+		const options = this.optionsService.readRuntimeOptions(optionArgs);
+		await new DevCommand().run({
+			appReference: target,
+			host: options.host,
+			port: options.port,
+			json: options.json,
+			documentGrantMap: options.documentGrantMap,
+			write: this.write
+		});
+	};
+	handlePack = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("pack", restArgs);
+		const options = this.optionsService.readPackOptions(optionArgs);
+		await new PackCommand().run({
+			appDirectory: target,
+			outputPath: options.outputPath,
+			json: options.json,
+			write: this.write
+		});
+	};
+	handleInstall = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("install", restArgs);
+		const options = this.optionsService.readInstallOptions(optionArgs);
+		await new InstallCommand().run({
+			appSource: target,
+			registryUrl: options.registryUrl,
+			json: options.json,
+			write: this.write
+		});
+	};
+	handleUpdate = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("update", restArgs);
+		const options = this.optionsService.readUpdateOptions(optionArgs);
+		await new UpdateCommand().run({
+			appId: target,
+			version: options.version,
+			registryUrl: options.registryUrl,
+			json: options.json,
+			write: this.write
+		});
+	};
+	handleUninstall = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("uninstall", restArgs);
+		const options = this.optionsService.readUninstallOptions(optionArgs);
+		await new UninstallCommand().run({
+			appId: target,
+			purgeData: options.purgeData,
+			json: options.json,
+			write: this.write
+		});
+	};
+	handleList = async (restArgs) => {
+		const options = this.optionsService.readJsonOnlyOptions(restArgs);
+		await new ListCommand().run({
+			json: options.json,
+			write: this.write
+		});
+	};
+	handleInfo = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("info", restArgs);
+		const options = this.optionsService.readJsonOnlyOptions(optionArgs);
+		await new InfoCommand().run({
+			appId: target,
+			json: options.json,
+			write: this.write
+		});
+	};
+	handleRegistry = async (restArgs) => {
+		const [actionOrUrl, ...optionArgs] = restArgs;
+		if (!actionOrUrl || actionOrUrl === "get") {
+			const options = this.optionsService.readJsonOnlyOptions(optionArgs);
+			await new RegistryCommand().run({
+				action: "get",
+				json: options.json,
+				write: this.write
+			});
+			return;
+		}
+		if (actionOrUrl === "--json") {
+			const options = this.optionsService.readJsonOnlyOptions([actionOrUrl, ...optionArgs]);
+			await new RegistryCommand().run({
+				action: "get",
+				json: options.json,
+				write: this.write
+			});
+			return;
+		}
+		if (actionOrUrl === "set") {
+			const { target, optionArgs: actionOptionArgs } = this.optionsService.readTarget("registry set", optionArgs);
+			const options = this.optionsService.readJsonOnlyOptions(actionOptionArgs);
+			await new RegistryCommand().run({
+				action: "set",
+				registryUrl: target,
+				json: options.json,
+				write: this.write
+			});
+			return;
+		}
+		if (actionOrUrl === "reset") {
+			const options = this.optionsService.readJsonOnlyOptions(optionArgs);
+			await new RegistryCommand().run({
+				action: "reset",
+				json: options.json,
+				write: this.write
+			});
+			return;
+		}
+		throw new Error(`未知 registry 子命令：${actionOrUrl}`);
+	};
+	handlePermissions = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("permissions", restArgs);
+		const options = this.optionsService.readJsonOnlyOptions(optionArgs);
+		await new PermissionsCommand().run({
+			appId: target,
+			json: options.json,
+			write: this.write
+		});
+	};
+	handleGrant = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("grant", restArgs);
+		const options = this.optionsService.readGrantOptions(optionArgs);
+		await new GrantCommand().run({
+			appId: target,
+			documentGrantMap: options.documentGrantMap,
+			json: options.json,
+			write: this.write
+		});
+	};
+	handleRevoke = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("revoke", restArgs);
+		const options = this.optionsService.readRevokeOptions(optionArgs);
+		await new RevokeCommand().run({
+			appId: target,
+			documentScopeIds: options.documentScopeIds,
+			json: options.json,
+			write: this.write
+		});
+	};
+	writeUsage = () => {
+		this.write("Usage: napp create <app-dir> [--json]\n");
+		this.write("       napp inspect <app-dir> [--json]\n");
+		this.write("       napp <run|dev> <app-dir|app-id> [--host 127.0.0.1] [--port 3100] [--json] [--document scope=/path]\n");
+		this.write("       napp pack <app-dir> [--out bundle.napp] [--json]\n");
+		this.write("       napp install <app-dir|bundle.napp|app-id[@version]> [--registry <url>] [--json]\n");
+		this.write("       napp update <app-id> [--version <version>] [--registry <url>] [--json]\n");
+		this.write("       napp uninstall <app-id> [--purge-data] [--json]\n");
+		this.write("       napp list [--json]\n");
+		this.write("       napp info <app-id> [--json]\n");
+		this.write("       napp registry [get] [--json]\n");
+		this.write("       napp registry set <url> [--json]\n");
+		this.write("       napp registry reset [--json]\n");
+		this.write("       napp permissions <app-id> [--json]\n");
+		this.write("       napp grant <app-id> --document scope=/path [--json]\n");
+		this.write("       napp revoke <app-id> --document scope [--json]\n");
+		this.write("       napp --help\n");
+		this.write("       napp --version\n");
+	};
+	write = (text) => {
+		process.stdout.write(text);
+	};
+};
+//#endregion
+export { AppRuntimeCliService };