@nextclaw/app-runtime 0.3.0 → 0.4.1

package/README.md

@@ -9,6 +9,7 @@
 - `napp run <app-dir|app-id>`：启动本地宿主，支持目录运行和已安装应用运行
 - `napp dev <app-dir>`：当前等价于 `run`
 - `napp pack <app-dir>`：把应用目录打成 `.napp` bundle
+- `napp publish <app-dir>`：把应用目录发布到官方 apps registry
 - `napp install <app-dir|bundle.napp|app-id[@version]>`：从本地或 registry 安装应用
 - `napp update <app-id>`：更新已安装应用
 - `napp uninstall <app-id>`：卸载已安装应用
@@ -57,7 +58,7 @@ assets/
 - 用户数据目录：`~/.nextclaw/apps/data/<app-id>/`
 - 本地 registry：`~/.nextclaw/apps/registry.json`
 - 本地 config：`~/.nextclaw/apps/config.json`
-- 默认 registry：`https://registry.nextclaw.com/`
+- 默认 registry：`https://apps-registry.nextclaw.io/api/v1/apps/registry/`
 
 ## 当前 MVP 工作流
 
@@ -67,6 +68,7 @@ assets/
 napp create ./my-first-napp
 napp inspect ./my-first-napp
 napp pack ./my-first-napp
+napp publish ./my-first-napp
 ```
 
 本地安装工作流：
@@ -115,6 +117,7 @@ napp run nextclaw.my-first-napp
 ```bash
 napp inspect ./apps/examples/hello-notes
 napp pack ./apps/examples/hello-notes
+napp publish ./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
@@ -129,6 +132,11 @@ napp install nextclaw.hello-notes
 napp update nextclaw.hello-notes
 ```
 
+官方 apps 入口：
+
+- Web：`https://apps.nextclaw.io`
+- Registry/API：`https://apps-registry.nextclaw.io`
+
 ## Bundle 结构
 
 `.napp` bundle 的最小结构如下：

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

@@ -11,6 +11,7 @@ declare class AppRuntimeCliService {
   private handleRun;
   private handleDev;
   private handlePack;
+  private handlePublish;
   private handleInstall;
   private handleUpdate;
   private handleUninstall;

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

@@ -9,6 +9,7 @@ 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 { PublishCommand } from "../commands/publish.controller.js";
 import { RegistryCommand } from "../commands/registry.controller.js";
 import { RevokeCommand } from "../commands/revoke.controller.js";
 import { UninstallCommand } from "../commands/uninstall.controller.js";
@@ -52,6 +53,9 @@ var AppRuntimeCliService = class {
 			case "pack":
 				await this.handlePack(restArgs);
 				return;
+			case "publish":
+				await this.handlePublish(restArgs);
+				return;
 			case "install":
 				await this.handleInstall(restArgs);
 				return;
@@ -136,6 +140,18 @@ var AppRuntimeCliService = class {
 			write: this.write
 		});
 	};
+	handlePublish = async (restArgs) => {
+		const { target, optionArgs } = this.optionsService.readTarget("publish", restArgs);
+		const options = this.optionsService.readPublishOptions(optionArgs);
+		await new PublishCommand().run({
+			appDirectory: target,
+			metadataPath: options.metadataPath,
+			apiBaseUrl: options.apiBaseUrl,
+			token: options.token,
+			json: options.json,
+			write: this.write
+		});
+	};
 	handleInstall = async (restArgs) => {
 		const { target, optionArgs } = this.optionsService.readTarget("install", restArgs);
 		const options = this.optionsService.readInstallOptions(optionArgs);
@@ -259,6 +275,7 @@ var AppRuntimeCliService = class {
 		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 publish <app-dir> [--meta marketplace.json] [--api-base <url>] [--token <token>] [--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");

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

@@ -38,6 +38,12 @@ type RevokeCliOptions = {
   json: boolean;
   documentScopeIds: string[];
 };
+type PublishCliOptions = {
+  json: boolean;
+  metadataPath?: string;
+  apiBaseUrl?: string;
+  token?: string;
+};
 declare class AppRuntimeOptionsService {
   readTarget: (command: string, rawArgs: string[]) => {
     target: string;
@@ -52,9 +58,10 @@ declare class AppRuntimeOptionsService {
   readRuntimeOptions: (rawArgs: string[]) => RuntimeCliOptions;
   readGrantOptions: (rawArgs: string[]) => GrantCliOptions;
   readRevokeOptions: (rawArgs: string[]) => RevokeCliOptions;
+  readPublishOptions: (rawArgs: string[]) => PublishCliOptions;
   private assignDocumentGrant;
   private readDocumentScopeId;
   private requireOptionValue;
 }
 //#endregion
-export { AppRuntimeOptionsService, CreateCliOptions, GrantCliOptions, InstallCliOptions, JsonOnlyCliOptions, PackCliOptions, RevokeCliOptions, RuntimeCliOptions, UninstallCliOptions, UpdateCliOptions };
+export { AppRuntimeOptionsService, CreateCliOptions, GrantCliOptions, InstallCliOptions, JsonOnlyCliOptions, PackCliOptions, PublishCliOptions, RevokeCliOptions, RuntimeCliOptions, UninstallCliOptions, UpdateCliOptions };

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

@@ -193,6 +193,33 @@ var AppRuntimeOptionsService = class {
 		if (options.documentScopeIds.length === 0) throw new Error("revoke 至少需要一个 --document scope。");
 		return options;
 	};
+	readPublishOptions = (rawArgs) => {
+		const options = { json: false };
+		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 "--json":
+					options.json = true;
+					break;
+				case "--meta":
+					options.metadataPath = this.requireOptionValue(current, nextValue);
+					index += 1;
+					break;
+				case "--api-base":
+					options.apiBaseUrl = this.requireOptionValue(current, nextValue);
+					index += 1;
+					break;
+				case "--token":
+					options.token = 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 格式。");

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

@@ -0,0 +1,17 @@
+import { AppPublishService } from "../publish/app-publish.service.js";
+
+//#region src/commands/publish.controller.d.ts
+declare class PublishCommand {
+  private readonly publishService;
+  constructor(publishService?: AppPublishService);
+  run: (params: {
+    appDirectory: string;
+    metadataPath?: string;
+    apiBaseUrl?: string;
+    token?: string;
+    json: boolean;
+    write: (text: string) => void;
+  }) => Promise<void>;
+}
+//#endregion
+export { PublishCommand };

package/dist/commands/publish.controller.js

@@ -0,0 +1,29 @@
+import { AppPublishService } from "../publish/app-publish.service.js";
+//#region src/commands/publish.controller.ts
+var PublishCommand = class {
+	constructor(publishService = new AppPublishService()) {
+		this.publishService = publishService;
+	}
+	run = async (params) => {
+		const { appDirectory, metadataPath, apiBaseUrl, token, json, write } = params;
+		const result = await this.publishService.publish({
+			appDirectory,
+			metadataPath,
+			apiBaseUrl,
+			token
+		});
+		if (json) {
+			write(`${JSON.stringify({
+				ok: true,
+				publish: result
+			}, null, 2)}\n`);
+			return;
+		}
+		write(`${result.created ? "Published" : "Updated"} ${result.item.name} (${result.item.appId}) ${result.item.latestVersion}\n`);
+		write(`Bundle: ${result.bundle.path}\n`);
+		if (result.item.webUrl) write(`Details: ${result.item.webUrl}\n`);
+		write(`Install: ${result.item.install.command}\n`);
+	};
+};
+//#endregion
+export { PublishCommand };

package/dist/index.d.ts

@@ -10,7 +10,7 @@ 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 { AppRuntimeOptionsService, CreateCliOptions, GrantCliOptions, InstallCliOptions, JsonOnlyCliOptions, PackCliOptions, PublishCliOptions, 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";
@@ -28,10 +28,16 @@ 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 { AppMarketplaceMetadata, AppPublishFile, AppPublishPayload, AppPublishResult, DEFAULT_APP_MARKETPLACE_API_BASE } from "./publish/app-publish.types.js";
+import { AppMarketplaceClientService } from "./publish/app-marketplace-client.service.js";
+import { AppMarketplaceMetadataService } from "./publish/app-marketplace-metadata.service.js";
+import { PlatformAuthStateService, PlatformPublishAuthState } from "./publish/platform-auth-state.service.js";
+import { AppPublishService } from "./publish/app-publish.service.js";
+import { PublishCommand } from "./commands/publish.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 { 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 };
+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, AppMarketplaceClientService, AppMarketplaceMetadata, AppMarketplaceMetadataService, AppPermissionSummary, AppPermissions, AppPermissionsService, AppPublishFile, AppPublishPayload, AppPublishResult, AppPublishService, AppPublisher, AppRegistry, AppRegistryAppRecord, AppRegistryConfig, AppRegistryConfigService, AppRegistryConfigSnapshot, AppRegistryInstalledVersion, AppRegistryService, AppRemoteRegistryClientService, AppRemoteRegistryDocument, AppRemoteRegistryResolution, AppRemoteRegistryVersion, AppRunResult, AppRuntimeCliService, AppRuntimeOptionsService, AppUiManifest, AppUninstallResult, AppUpdateResult, CreateCliOptions, CreateCommand, DEFAULT_APP_MARKETPLACE_API_BASE, DEFAULT_APP_REGISTRY_URL, GrantCliOptions, GrantCommand, HostBridgeServer, InfoCommand, InstallCliOptions, InstallCommand, InstalledAppListItem, JsonOnlyCliOptions, ListCommand, MainRunRequest, MainRunResult, MainRunnerService, PackCliOptions, PackCommand, PermissionsCommand, PlatformAuthStateService, PlatformPublishAuthState, PublishCliOptions, PublishCommand, RegistryCommand, ResolvedDocumentGrant, ResolvedPermissions, RevokeCliOptions, RevokeCommand, RuntimeCliOptions, UiServerService, UninstallCliOptions, UninstallCommand, UpdateCliOptions, UpdateCommand, WasmDocumentSummaryInput, WasmMainRunnerService, WasmSidecarClientService };

package/dist/index.js

@@ -22,10 +22,16 @@ 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 { DEFAULT_APP_MARKETPLACE_API_BASE } from "./publish/app-publish.types.js";
+import { AppMarketplaceClientService } from "./publish/app-marketplace-client.service.js";
+import { AppMarketplaceMetadataService } from "./publish/app-marketplace-metadata.service.js";
+import { PlatformAuthStateService } from "./publish/platform-auth-state.service.js";
+import { AppPublishService } from "./publish/app-publish.service.js";
+import { PublishCommand } from "./commands/publish.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 };
+export { AppBundleService, AppGrantService, AppHomeService, AppHostService, AppInstallationService, AppInstanceService, AppManifestService, AppMarketplaceClientService, AppMarketplaceMetadataService, AppPermissionsService, AppPublishService, AppRegistryConfigService, AppRegistryService, AppRemoteRegistryClientService, AppRuntimeCliService, AppRuntimeOptionsService, CreateCommand, DEFAULT_APP_MARKETPLACE_API_BASE, DEFAULT_APP_REGISTRY_URL, GrantCommand, HostBridgeServer, InfoCommand, InstallCommand, ListCommand, MainRunnerService, PackCommand, PermissionsCommand, PlatformAuthStateService, PublishCommand, RegistryCommand, RevokeCommand, UiServerService, UninstallCommand, UpdateCommand, WasmMainRunnerService, WasmSidecarClientService };

package/dist/package.js

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

package/dist/publish/app-marketplace-client.service.d.ts

@@ -0,0 +1,13 @@
+import { AppPublishPayload, AppPublishResult } from "./app-publish.types.js";
+
+//#region src/publish/app-marketplace-client.service.d.ts
+declare class AppMarketplaceClientService {
+  publish: (params: {
+    payload: AppPublishPayload;
+    apiBaseUrl?: string;
+    token?: string;
+  }) => Promise<AppPublishResult>;
+  private normalizeApiBase;
+}
+//#endregion
+export { AppMarketplaceClientService };

package/dist/publish/app-marketplace-client.service.js

@@ -0,0 +1,31 @@
+import "./app-publish.types.js";
+//#region src/publish/app-marketplace-client.service.ts
+var AppMarketplaceClientService = class {
+	publish = async (params) => {
+		const apiBaseUrl = this.normalizeApiBase(params.apiBaseUrl ?? "https://apps-registry.nextclaw.io");
+		const token = params.token?.trim();
+		if (!token) throw new Error("缺少 marketplace publish token。请先登录 NextClaw，或传入 --token。");
+		const response = await fetch(`${apiBaseUrl}/api/v1/apps/publish`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${token}`,
+				accept: "application/json"
+			},
+			body: JSON.stringify(params.payload)
+		});
+		const payload = await response.json().catch(() => null);
+		if (!response.ok) {
+			const message = typeof payload === "object" && payload && "error" in payload && typeof payload.error?.message === "string" ? payload.error.message : `${response.status} ${response.statusText}`;
+			throw new Error(`发布 app 失败：${message}`);
+		}
+		const data = typeof payload === "object" && payload && "data" in payload && typeof payload.data === "object" ? payload.data : null;
+		if (!data) throw new Error("marketplace publish 返回格式无效。");
+		return data;
+	};
+	normalizeApiBase = (apiBaseUrl) => {
+		return new URL(apiBaseUrl).toString().replace(/\/+$/, "");
+	};
+};
+//#endregion
+export { AppMarketplaceClientService };

package/dist/publish/app-marketplace-metadata.service.d.ts

@@ -0,0 +1,27 @@
+import { AppManifest } from "../manifest/app-manifest.types.js";
+import { AppMarketplaceMetadata } from "./app-publish.types.js";
+
+//#region src/publish/app-marketplace-metadata.service.d.ts
+declare class AppMarketplaceMetadataService {
+  load: (params: {
+    appDirectory: string;
+    manifest: AppManifest;
+    metadataPath?: string;
+  }) => Promise<AppMarketplaceMetadata>;
+  collectPublishFiles: (params: {
+    appDirectory: string;
+    metadataPath?: string;
+  }) => Promise<Array<{
+    path: string;
+    bytes: Buffer;
+  }>>;
+  private parseMetadata;
+  private parsePublisher;
+  private readRequiredString;
+  private readOptionalString;
+  private readStringArray;
+  private readOptionalBoolean;
+  private readLocalizedTextMap;
+}
+//#endregion
+export { AppMarketplaceMetadataService };

package/dist/publish/app-marketplace-metadata.service.js

@@ -0,0 +1,84 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { existsSync } from "node:fs";
+//#region src/publish/app-marketplace-metadata.service.ts
+var AppMarketplaceMetadataService = class {
+	load = async (params) => {
+		const { appDirectory, manifest, metadataPath: customMetadataPath } = params;
+		const metadataPath = customMetadataPath ? path.resolve(customMetadataPath) : path.join(path.resolve(appDirectory), "marketplace.json");
+		const raw = JSON.parse(await readFile(metadataPath, "utf-8"));
+		return this.parseMetadata(raw, manifest);
+	};
+	collectPublishFiles = async (params) => {
+		const appDirectory = path.resolve(params.appDirectory);
+		const publishFiles = [];
+		const metadataPath = params.metadataPath ? path.resolve(params.metadataPath) : path.join(appDirectory, "marketplace.json");
+		publishFiles.push({
+			path: "marketplace.json",
+			bytes: Buffer.from(await readFile(metadataPath))
+		});
+		const readmePath = path.join(appDirectory, "README.md");
+		if (existsSync(readmePath)) publishFiles.push({
+			path: "README.md",
+			bytes: Buffer.from(await readFile(readmePath))
+		});
+		return publishFiles;
+	};
+	parseMetadata = (rawMetadata, manifest) => {
+		if (!rawMetadata || typeof rawMetadata !== "object" || Array.isArray(rawMetadata)) throw new Error("marketplace.json 必须是对象。");
+		const candidate = rawMetadata;
+		const slug = this.readRequiredString(candidate.slug, "slug");
+		const summary = this.readRequiredString(candidate.summary, "summary");
+		const description = this.readOptionalString(candidate.description, "description");
+		const author = this.readOptionalString(candidate.author, "author") ?? manifest.name;
+		const publisher = this.parsePublisher(candidate.publisher);
+		return {
+			slug,
+			summary,
+			summaryI18n: this.readLocalizedTextMap(candidate.summaryI18n, "summaryI18n", summary),
+			description,
+			descriptionI18n: description ? this.readLocalizedTextMap(candidate.descriptionI18n, "descriptionI18n", description) : void 0,
+			author,
+			tags: this.readStringArray(candidate.tags, "tags"),
+			sourceRepo: this.readOptionalString(candidate.sourceRepo, "sourceRepo"),
+			homepage: this.readOptionalString(candidate.homepage, "homepage"),
+			featured: this.readOptionalBoolean(candidate.featured, "featured") ?? false,
+			publisher
+		};
+	};
+	parsePublisher = (rawPublisher) => {
+		if (rawPublisher === void 0) return;
+		if (!rawPublisher || typeof rawPublisher !== "object" || Array.isArray(rawPublisher)) throw new Error("publisher 必须是对象。");
+		const candidate = rawPublisher;
+		return {
+			id: this.readRequiredString(candidate.id, "publisher.id"),
+			name: this.readRequiredString(candidate.name, "publisher.name"),
+			url: this.readOptionalString(candidate.url, "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);
+	};
+	readStringArray = (value, fieldName) => {
+		if (!Array.isArray(value) || value.length === 0) throw new Error(`${fieldName} 必须是非空字符串数组。`);
+		return value.map((item, index) => this.readRequiredString(item, `${fieldName}[${index}]`));
+	};
+	readOptionalBoolean = (value, fieldName) => {
+		if (value === void 0) return;
+		if (typeof value !== "boolean") throw new Error(`${fieldName} 必须是布尔值。`);
+		return value;
+	};
+	readLocalizedTextMap = (value, fieldName, fallbackEn) => {
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${fieldName} 必须是对象。`);
+		const normalized = Object.fromEntries(Object.entries(value).map(([locale, localeValue]) => [locale, this.readRequiredString(localeValue, `${fieldName}.${locale}`)]));
+		if (!normalized.en) normalized.en = fallbackEn;
+		return normalized;
+	};
+};
+//#endregion
+export { AppMarketplaceMetadataService };

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

@@ -0,0 +1,29 @@
+import { AppManifestService } from "../manifest/app-manifest.service.js";
+import { AppBundleService } from "../bundle/app-bundle.service.js";
+import { AppPublishResult } from "./app-publish.types.js";
+import { AppMarketplaceClientService } from "./app-marketplace-client.service.js";
+import { AppMarketplaceMetadataService } from "./app-marketplace-metadata.service.js";
+import { PlatformAuthStateService } from "./platform-auth-state.service.js";
+
+//#region src/publish/app-publish.service.d.ts
+declare class AppPublishService {
+  private readonly manifestService;
+  private readonly bundleService;
+  private readonly metadataService;
+  private readonly marketplaceClient;
+  private readonly authStateService;
+  constructor(manifestService?: AppManifestService, bundleService?: AppBundleService, metadataService?: AppMarketplaceMetadataService, marketplaceClient?: AppMarketplaceClientService, authStateService?: PlatformAuthStateService);
+  publish: (params: {
+    appDirectory: string;
+    metadataPath?: string;
+    apiBaseUrl?: string;
+    token?: string;
+  }) => Promise<AppPublishResult>;
+  private resolvePublishActor;
+  private fetchCurrentPlatformUser;
+  private resolvePlatformApiBase;
+  private buildUserPublisher;
+  private buildOfficialPublisher;
+}
+//#endregion
+export { AppPublishService };

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

@@ -0,0 +1,154 @@
+import { AppManifestService } from "../manifest/app-manifest.service.js";
+import { AppBundleService } from "../bundle/app-bundle.service.js";
+import { AppMarketplaceClientService } from "./app-marketplace-client.service.js";
+import { AppMarketplaceMetadataService } from "./app-marketplace-metadata.service.js";
+import { PlatformAuthStateService } from "./platform-auth-state.service.js";
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+//#region src/publish/app-publish.service.ts
+const DEFAULT_PLATFORM_API_BASE = "https://ai-gateway-api.nextclaw.io";
+var AppPublishService = class {
+	constructor(manifestService = new AppManifestService(), bundleService = new AppBundleService(), metadataService = new AppMarketplaceMetadataService(), marketplaceClient = new AppMarketplaceClientService(), authStateService = new PlatformAuthStateService()) {
+		this.manifestService = manifestService;
+		this.bundleService = bundleService;
+		this.metadataService = metadataService;
+		this.marketplaceClient = marketplaceClient;
+		this.authStateService = authStateService;
+	}
+	publish = async (params) => {
+		const { appDirectory: inputAppDirectory, metadataPath, apiBaseUrl, token } = params;
+		const appDirectory = path.resolve(inputAppDirectory);
+		const manifestBundle = await this.manifestService.load(appDirectory);
+		const metadata = await this.metadataService.load({
+			appDirectory,
+			manifest: manifestBundle.manifest,
+			metadataPath
+		});
+		const actor = await this.resolvePublishActor({
+			apiBaseUrl,
+			explicitToken: token,
+			appId: manifestBundle.manifest.id
+		});
+		const bundle = await this.bundleService.packAppDirectory({ appDirectory });
+		const bundleBytes = Buffer.from(await readFile(bundle.bundlePath));
+		const bundleSha256 = createHash("sha256").update(bundleBytes).digest("hex");
+		const publishFiles = await this.metadataService.collectPublishFiles({
+			appDirectory,
+			metadataPath
+		});
+		const payload = {
+			slug: metadata.slug,
+			appId: manifestBundle.manifest.id,
+			name: manifestBundle.manifest.name,
+			version: manifestBundle.manifest.version,
+			summary: metadata.summary,
+			summaryI18n: metadata.summaryI18n,
+			description: metadata.description ?? manifestBundle.manifest.description,
+			descriptionI18n: metadata.descriptionI18n,
+			author: metadata.author,
+			tags: metadata.tags,
+			sourceRepo: metadata.sourceRepo,
+			homepage: metadata.homepage,
+			featured: metadata.featured ?? false,
+			publisher: actor.publisher,
+			manifest: manifestBundle.manifest,
+			permissions: manifestBundle.manifest.permissions ?? {},
+			bundleBase64: bundleBytes.toString("base64"),
+			bundleSha256,
+			files: publishFiles.map((file) => ({
+				path: file.path,
+				contentBase64: file.bytes.toString("base64")
+			}))
+		};
+		return {
+			...await this.marketplaceClient.publish({
+				payload,
+				apiBaseUrl,
+				token: actor.token
+			}),
+			bundle: {
+				path: bundle.bundlePath,
+				sha256: bundleSha256
+			}
+		};
+	};
+	resolvePublishActor = async (params) => {
+		const explicitToken = params.explicitToken?.trim();
+		const envAdminToken = process.env.NEXTCLAW_MARKETPLACE_ADMIN_TOKEN?.trim();
+		if (explicitToken) {
+			const token = explicitToken;
+			if (!token) throw new Error("缺少 publish token。");
+			const me = await this.fetchCurrentPlatformUser({
+				token,
+				platformApiBase: this.resolvePlatformApiBase()
+			});
+			return {
+				token,
+				publisher: this.buildUserPublisher(me, params.appId)
+			};
+		}
+		const authState = this.authStateService.readCurrentAuthState();
+		const platformToken = authState.token?.trim();
+		if (platformToken) {
+			const me = await this.fetchCurrentPlatformUser({
+				token: platformToken,
+				platformApiBase: this.resolvePlatformApiBase(authState.apiBaseUrl)
+			});
+			return {
+				token: platformToken,
+				publisher: this.buildUserPublisher(me, params.appId)
+			};
+		}
+		if (envAdminToken) return {
+			token: envAdminToken,
+			publisher: this.buildOfficialPublisher()
+		};
+		throw new Error("发布需要 NextClaw 平台登录态。请先运行 nextclaw login，或传入 --token。");
+	};
+	fetchCurrentPlatformUser = async (params) => {
+		const response = await fetch(`${params.platformApiBase}/platform/auth/me`, { headers: {
+			authorization: `Bearer ${params.token}`,
+			accept: "application/json"
+		} });
+		const payload = await response.json().catch(() => null);
+		if (!response.ok) {
+			const message = typeof payload === "object" && payload && "error" in payload && typeof payload.error?.message === "string" ? payload.error.message : `${response.status} ${response.statusText}`;
+			throw new Error(`读取 NextClaw 登录态失败：${message}`);
+		}
+		const user = typeof payload === "object" && payload && "data" in payload && typeof payload.data?.user === "object" && payload.data.user ? payload.data.user : null;
+		const id = typeof user?.id === "string" ? user.id.trim() : "";
+		const username = typeof user?.username === "string" ? user.username.trim() : "";
+		const role = user?.role === "admin" ? "admin" : "user";
+		if (!id) throw new Error("平台登录态缺少用户 id。");
+		return {
+			id,
+			username: username || null,
+			role
+		};
+	};
+	resolvePlatformApiBase = (configuredApiBase) => {
+		const source = configuredApiBase?.trim() || process.env.NEXTCLAW_PLATFORM_API_BASE?.trim() || DEFAULT_PLATFORM_API_BASE;
+		const normalized = new URL(source);
+		normalized.pathname = normalized.pathname.replace(/\/v1\/?$/, "/");
+		return normalized.toString().replace(/\/+$/, "");
+	};
+	buildUserPublisher = (user, appId) => {
+		if (appId.startsWith("nextclaw.") && user.role === "admin") return this.buildOfficialPublisher();
+		if (!user.username) throw new Error("当前 NextClaw 账号还没有 username，无法发布个人 scope app。请先在平台账号页设置用户名。");
+		return {
+			id: user.username,
+			name: user.username,
+			url: `https://platform.nextclaw.io/account`
+		};
+	};
+	buildOfficialPublisher = () => {
+		return {
+			id: "nextclaw",
+			name: "NextClaw",
+			url: "https://nextclaw.io"
+		};
+	};
+};
+//#endregion
+export { AppPublishService };

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/publish/platform-auth-state.service.d.ts

@@ -0,0 +1,11 @@
+//#region src/publish/platform-auth-state.service.d.ts
+type PlatformPublishAuthState = {
+  token: string | null;
+  apiBaseUrl?: string;
+};
+declare class PlatformAuthStateService {
+  readCurrentAuthState: () => PlatformPublishAuthState;
+  private resolveConfigPath;
+}
+//#endregion
+export { PlatformAuthStateService, PlatformPublishAuthState };

package/dist/publish/platform-auth-state.service.js

@@ -0,0 +1,26 @@
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+//#region src/publish/platform-auth-state.service.ts
+var PlatformAuthStateService = class {
+	readCurrentAuthState = () => {
+		const configPath = this.resolveConfigPath();
+		if (!existsSync(configPath)) return { token: null };
+		try {
+			const raw = readFileSync(configPath, "utf-8");
+			const provider = JSON.parse(raw).providers?.nextclaw;
+			return {
+				token: typeof provider?.apiKey === "string" && provider.apiKey.trim().length > 0 ? provider.apiKey.trim() : null,
+				apiBaseUrl: typeof provider?.apiBase === "string" && provider.apiBase.trim().length > 0 ? provider.apiBase.trim() : void 0
+			};
+		} catch {
+			return { token: null };
+		}
+	};
+	resolveConfigPath = () => {
+		const nextclawHome = process.env.NEXTCLAW_HOME?.trim();
+		return resolve(nextclawHome && nextclawHome.length > 0 ? resolve(nextclawHome) : resolve(homedir(), ".nextclaw"), "config.json");
+	};
+};
+//#endregion
+export { PlatformAuthStateService };

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

@@ -1,7 +1,7 @@
 import { AppPermissions } from "../manifest/app-manifest.types.js";
 
 //#region src/registry/app-remote-registry.types.d.ts
-declare const DEFAULT_APP_REGISTRY_URL = "https://registry.nextclaw.com/";
+declare const DEFAULT_APP_REGISTRY_URL = "https://apps-registry.nextclaw.io/api/v1/apps/registry/";
 type AppPublisher = {
   id: string;
   name: string;

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

@@ -1,4 +1,4 @@
 //#region src/registry/app-remote-registry.types.ts
-const DEFAULT_APP_REGISTRY_URL = "https://registry.nextclaw.com/";
+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

@@ -12,6 +12,8 @@ declare class AppScaffoldService {
   private buildManifest;
   private buildWatSource;
   private buildUiHtml;
+  private buildMarketplaceMetadata;
+  private buildReadme;
   private buildUiController;
   private buildIconSvg;
 }

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,53 @@ 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
+		};
+	};
+	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 = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/app-runtime",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "private": false,
   "description": "Standalone micro app runtime and CLI for NextClaw apps.",
   "type": "module",