@nextclaw/app-runtime 0.2.0 → 0.4.0

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

@@ -0,0 +1,66 @@
+import { AppManifest, AppPermissions } from "../manifest/app-manifest.types.js";
+import { AppPublisher } from "../registry/app-remote-registry.types.js";
+
+//#region src/publish/app-publish.types.d.ts
+declare const DEFAULT_APP_MARKETPLACE_API_BASE = "https://apps-registry.nextclaw.io";
+type AppMarketplaceMetadata = {
+  slug: string;
+  summary: string;
+  summaryI18n: Record<string, string>;
+  description?: string;
+  descriptionI18n?: Record<string, string>;
+  author: string;
+  tags: string[];
+  sourceRepo?: string;
+  homepage?: string;
+  featured?: boolean;
+  publisher?: AppPublisher;
+};
+type AppPublishFile = {
+  path: string;
+  contentBase64: string;
+};
+type AppPublishPayload = {
+  slug: string;
+  appId: string;
+  name: string;
+  version: string;
+  summary: string;
+  summaryI18n: Record<string, string>;
+  description?: string;
+  descriptionI18n?: Record<string, string>;
+  author: string;
+  tags: string[];
+  sourceRepo?: string;
+  homepage?: string;
+  featured: boolean;
+  publisher: AppPublisher;
+  manifest: AppManifest;
+  permissions: AppPermissions;
+  bundleBase64: string;
+  bundleSha256: string;
+  files: AppPublishFile[];
+};
+type AppPublishResult = {
+  created: boolean;
+  item: {
+    slug: string;
+    appId: string;
+    name: string;
+    latestVersion: string;
+    webUrl?: string;
+    install: {
+      kind: "registry";
+      spec: string;
+      command: string;
+      registry: string;
+    };
+  };
+  bundle: {
+    path: string;
+    sha256: string;
+  };
+  fileCount: number;
+};
+//#endregion
+export { AppMarketplaceMetadata, AppPublishFile, AppPublishPayload, AppPublishResult, DEFAULT_APP_MARKETPLACE_API_BASE };

package/dist/publish/app-publish.types.js

@@ -0,0 +1,4 @@
+//#region src/publish/app-publish.types.ts
+const DEFAULT_APP_MARKETPLACE_API_BASE = "https://apps-registry.nextclaw.io";
+//#endregion
+export { DEFAULT_APP_MARKETPLACE_API_BASE };

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 };

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

@@ -0,0 +1,28 @@
+import { AppRemoteRegistryResolution } from "./app-remote-registry.types.js";
+import { AppRegistryConfigService } from "./app-registry-config.service.js";
+
+//#region src/registry/app-remote-registry-client.service.d.ts
+declare class AppRemoteRegistryClientService {
+  private readonly configService;
+  constructor(configService?: AppRegistryConfigService);
+  resolve: (params: {
+    appId: string;
+    version?: string;
+    registryUrl?: string;
+  }) => Promise<AppRemoteRegistryResolution>;
+  downloadBundle: (params: {
+    resolution: AppRemoteRegistryResolution;
+    targetDirectory: string;
+  }) => Promise<{
+    bundlePath: string;
+  }>;
+  private parseDocument;
+  private parseVersion;
+  private parsePublisher;
+  private readRequiredString;
+  private readOptionalString;
+  private normalizeBundleFileName;
+  private normalizeRegistryUrl;
+}
+//#endregion
+export { AppRemoteRegistryClientService };

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

@@ -0,0 +1,114 @@
+import { AppRegistryConfigService } from "./app-registry-config.service.js";
+import { writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+//#region src/registry/app-remote-registry-client.service.ts
+var AppRemoteRegistryClientService = class {
+	constructor(configService = new AppRegistryConfigService()) {
+		this.configService = configService;
+	}
+	resolve = async (params) => {
+		const { appId, version: requestedVersion, registryUrl: overrideRegistryUrl } = params;
+		const registryUrl = overrideRegistryUrl ? this.normalizeRegistryUrl(overrideRegistryUrl) : (await this.configService.getSnapshot()).currentUrl;
+		const metadataUrl = new URL(encodeURIComponent(appId), registryUrl).toString();
+		const response = await fetch(metadataUrl);
+		if (!response.ok) throw new Error(`无法从 registry 拉取 ${appId} metadata：${response.status} ${response.statusText}`);
+		const document = this.parseDocument(await response.json(), appId);
+		const version = requestedVersion ?? document["dist-tags"].latest;
+		const versionRecord = document.versions[version];
+		if (!versionRecord) throw new Error(`registry ${registryUrl} 未提供 ${appId}@${version}。`);
+		return {
+			registryUrl,
+			metadataUrl,
+			appId,
+			version,
+			description: versionRecord.description ?? document.description,
+			publisher: versionRecord.publisher,
+			permissions: versionRecord.permissions,
+			bundleUrl: new URL(versionRecord.dist.bundle, metadataUrl).toString(),
+			sha256: versionRecord.dist.sha256
+		};
+	};
+	downloadBundle = async (params) => {
+		const { resolution, targetDirectory } = params;
+		const response = await fetch(resolution.bundleUrl);
+		if (!response.ok) throw new Error(`无法下载 bundle：${resolution.bundleUrl} (${response.status} ${response.statusText})`);
+		const bundleBytes = Buffer.from(await response.arrayBuffer());
+		const actualSha256 = createHash("sha256").update(bundleBytes).digest("hex");
+		if (actualSha256 !== resolution.sha256) throw new Error(`bundle checksum 校验失败：期望 ${resolution.sha256}，实际 ${actualSha256}`);
+		const bundlePath = path.join(targetDirectory, `${this.normalizeBundleFileName(resolution.appId)}-${resolution.version}.napp`);
+		await writeFile(bundlePath, bundleBytes);
+		return { bundlePath };
+	};
+	parseDocument = (rawDocument, appId) => {
+		if (!rawDocument || typeof rawDocument !== "object" || Array.isArray(rawDocument)) throw new Error(`registry ${appId} metadata 必须是对象。`);
+		const candidate = rawDocument;
+		const name = this.readRequiredString(candidate.name, "name");
+		if (name !== appId) throw new Error(`registry 返回的包名与请求不一致：请求 ${appId}，收到 ${name}`);
+		const distTags = candidate["dist-tags"];
+		if (!distTags || typeof distTags !== "object" || Array.isArray(distTags)) throw new Error("registry metadata 缺少 dist-tags。");
+		const versions = candidate.versions;
+		if (!versions || typeof versions !== "object" || Array.isArray(versions)) throw new Error("registry metadata 缺少 versions。");
+		return {
+			name,
+			description: this.readOptionalString(candidate.description, "description"),
+			"dist-tags": { latest: this.readRequiredString(distTags.latest, "dist-tags.latest") },
+			versions: Object.fromEntries(Object.entries(versions).map(([version, rawVersion]) => [version, this.parseVersion(rawVersion, name, version)]))
+		};
+	};
+	parseVersion = (rawVersion, appId, version) => {
+		if (!rawVersion || typeof rawVersion !== "object" || Array.isArray(rawVersion)) throw new Error(`registry metadata 的 versions.${version} 必须是对象。`);
+		const candidate = rawVersion;
+		const name = this.readRequiredString(candidate.name, `versions.${version}.name`);
+		const parsedVersion = this.readRequiredString(candidate.version, `versions.${version}.version`);
+		if (name !== appId || parsedVersion !== version) throw new Error(`registry metadata 的 versions.${version} 与 app id/version 不一致。`);
+		const dist = candidate.dist;
+		if (!dist || typeof dist !== "object" || Array.isArray(dist)) throw new Error(`registry metadata 的 versions.${version}.dist 必须是对象。`);
+		const distCandidate = dist;
+		return {
+			name,
+			version: parsedVersion,
+			description: this.readOptionalString(candidate.description, `versions.${version}.description`),
+			publisher: this.parsePublisher(candidate.publisher, version),
+			permissions: candidate.permissions,
+			dist: {
+				bundle: this.readRequiredString(distCandidate.bundle, `versions.${version}.dist.bundle`),
+				sha256: this.readRequiredString(distCandidate.sha256, `versions.${version}.dist.sha256`)
+			}
+		};
+	};
+	parsePublisher = (rawPublisher, version) => {
+		if (rawPublisher === void 0) return;
+		if (!rawPublisher || typeof rawPublisher !== "object" || Array.isArray(rawPublisher)) throw new Error(`versions.${version}.publisher 必须是对象。`);
+		const candidate = rawPublisher;
+		return {
+			id: this.readRequiredString(candidate.id, `versions.${version}.publisher.id`),
+			name: this.readRequiredString(candidate.name, `versions.${version}.publisher.name`),
+			url: this.readOptionalString(candidate.url, `versions.${version}.publisher.url`)
+		};
+	};
+	readRequiredString = (value, fieldName) => {
+		if (typeof value !== "string" || !value.trim()) throw new Error(`${fieldName} 必须是非空字符串。`);
+		return value.trim();
+	};
+	readOptionalString = (value, fieldName) => {
+		if (value === void 0) return;
+		return this.readRequiredString(value, fieldName);
+	};
+	normalizeBundleFileName = (appId) => {
+		return appId.replace(/[^a-zA-Z0-9._-]+/g, "-");
+	};
+	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 { AppRemoteRegistryClientService };

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

@@ -0,0 +1,52 @@
+import { AppPermissions } from "../manifest/app-manifest.types.js";
+
+//#region src/registry/app-remote-registry.types.d.ts
+declare const DEFAULT_APP_REGISTRY_URL = "https://apps-registry.nextclaw.io/api/v1/apps/registry/";
+type AppPublisher = {
+  id: string;
+  name: string;
+  url?: string;
+};
+type AppRegistryConfig = {
+  schemaVersion: 1;
+  registry: {
+    url: string;
+  };
+};
+type AppRegistryConfigSnapshot = {
+  defaultUrl: string;
+  currentUrl: string;
+  source: "default" | "config" | "env";
+};
+type AppRemoteRegistryVersion = {
+  name: string;
+  version: string;
+  description?: string;
+  publisher?: AppPublisher;
+  permissions?: AppPermissions;
+  dist: {
+    bundle: string;
+    sha256: string;
+  };
+};
+type AppRemoteRegistryDocument = {
+  name: string;
+  description?: string;
+  "dist-tags": {
+    latest: string;
+  };
+  versions: Record<string, AppRemoteRegistryVersion>;
+};
+type AppRemoteRegistryResolution = {
+  registryUrl: string;
+  metadataUrl: string;
+  appId: string;
+  version: string;
+  description?: string;
+  publisher?: AppPublisher;
+  permissions?: AppPermissions;
+  bundleUrl: string;
+  sha256: string;
+};
+//#endregion
+export { AppPublisher, AppRegistryConfig, AppRegistryConfigSnapshot, AppRemoteRegistryDocument, AppRemoteRegistryResolution, AppRemoteRegistryVersion, DEFAULT_APP_REGISTRY_URL };

package/dist/registry/app-remote-registry.types.js

@@ -0,0 +1,4 @@
+//#region src/registry/app-remote-registry.types.ts
+const DEFAULT_APP_REGISTRY_URL = "https://apps-registry.nextclaw.io/api/v1/apps/registry/";
+//#endregion
+export { DEFAULT_APP_REGISTRY_URL };

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

@@ -0,0 +1,21 @@
+//#region src/scaffold/app-scaffold.service.d.ts
+type AppScaffoldResult = {
+  appDirectory: string;
+  manifestPath: string;
+};
+declare class AppScaffoldService {
+  scaffold: (targetDirectory: string) => Promise<AppScaffoldResult>;
+  private assertTargetDoesNotExist;
+  private buildAppId;
+  private buildAppName;
+  private normalizeSlug;
+  private buildManifest;
+  private buildWatSource;
+  private buildUiHtml;
+  private buildMarketplaceMetadata;
+  private buildReadme;
+  private buildUiController;
+  private buildIconSvg;
+}
+//#endregion
+export { AppScaffoldService };

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

@@ -13,6 +13,8 @@ var AppScaffoldService = class {
 		const manifestPath = path.join(appDirectory, "manifest.json");
 		await Promise.all([
 			writeFile(manifestPath, `${JSON.stringify(this.buildManifest(appId, appName), null, 2)}\n`, "utf-8"),
+			writeFile(path.join(appDirectory, "marketplace.json"), `${JSON.stringify(this.buildMarketplaceMetadata(appName), null, 2)}\n`, "utf-8"),
+			writeFile(path.join(appDirectory, "README.md"), this.buildReadme(appName, appId), "utf-8"),
 			writeFile(path.join(appDirectory, "main", "app.wasm"), Buffer.from(APP_WASM_BASE64, "base64")),
 			writeFile(path.join(appDirectory, "main", "app.wat"), this.buildWatSource(), "utf-8"),
 			writeFile(path.join(appDirectory, "ui", "index.html"), this.buildUiHtml(appName), "utf-8"),
@@ -191,6 +193,58 @@ var AppScaffoldService = class {
     <script type="module" src="./app.controller.js"><\/script>
   </body>
 </html>
+`;
+	};
+	buildMarketplaceMetadata = (appName) => {
+		return {
+			slug: this.normalizeSlug(appName),
+			summary: `A minimal ${appName} app scaffold created by napp.`,
+			summaryI18n: {
+				en: `A minimal ${appName} app scaffold created by napp.`,
+				zh: `一个由 napp 创建的最小 ${appName} 应用骨架。`
+			},
+			description: `A minimal NextClaw app scaffold for ${appName}, ready for local run and marketplace publish.`,
+			descriptionI18n: {
+				en: `A minimal NextClaw app scaffold for ${appName}, ready for local run and marketplace publish.`,
+				zh: `一个面向 ${appName} 的最小 NextClaw 应用骨架，可直接本地运行并发布到 marketplace。`
+			},
+			author: "NextClaw",
+			tags: [
+				"starter",
+				"official",
+				"local"
+			],
+			sourceRepo: "https://github.com/Peiiii/nextclaw",
+			homepage: "https://nextclaw.io",
+			featured: false,
+			publisher: {
+				id: "nextclaw",
+				name: "NextClaw",
+				url: "https://nextclaw.io"
+			}
+		};
+	};
+	buildReadme = (appName, appId) => {
+		return `# ${appName}
+
+This starter app was created by \`napp create\`.
+
+## Local workflow
+
+\`\`\`bash
+napp inspect .
+napp run .
+\`\`\`
+
+## Publish workflow
+
+\`\`\`bash
+napp publish .
+\`\`\`
+
+## App ID
+
+\`${appId}\`
 `;
 	};
 	buildUiController = () => {
@@ -255,6 +309,6 @@ await loadManifest();
 `;
 	};
 };
-const APP_WASM_BASE64 = "AGFzbQEAAAABBwFgAn9/AX8DAgEABxMBD3N1bW1hcml6ZV9ub3RlcwAACg0BCwAgACABagsQQQQK";
+const APP_WASM_BASE64 = "AGFzbQEAAAABBwFgAn9/AX8DAgEABxMBD3N1bW1hcml6ZV9ub3RlcwAACg0BCwAgACABakHIAWoL";
 //#endregion
 export { AppScaffoldService };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/app-runtime",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": false,
   "description": "Standalone micro app runtime and CLI for NextClaw apps.",
   "type": "module",
@@ -38,7 +38,9 @@
     "dist",
     "README.md"
   ],
-  "dependencies": {},
+  "dependencies": {
+    "fflate": "^0.8.2"
+  },
   "devDependencies": {
     "@types/node": "^20.17.6",
     "prettier": "^3.3.3",