@nextclaw/app-runtime 0.1.0 → 0.3.0

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://registry.nextclaw.com/";
+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://registry.nextclaw.com/";
+//#endregion
+export { DEFAULT_APP_REGISTRY_URL };

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

@@ -0,0 +1,19 @@
+//#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 buildUiController;
+  private buildIconSvg;
+}
+//#endregion
+export { AppScaffoldService };

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

@@ -0,0 +1,260 @@
+import { access, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+//#region src/scaffold/app-scaffold.service.ts
+var AppScaffoldService = class {
+	scaffold = async (targetDirectory) => {
+		const appDirectory = path.resolve(targetDirectory);
+		await this.assertTargetDoesNotExist(appDirectory);
+		await mkdir(path.join(appDirectory, "main"), { recursive: true });
+		await mkdir(path.join(appDirectory, "ui"), { recursive: true });
+		await mkdir(path.join(appDirectory, "assets"), { recursive: true });
+		const appName = this.buildAppName(appDirectory);
+		const appId = this.buildAppId(appDirectory);
+		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, "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"),
+			writeFile(path.join(appDirectory, "ui", "app.controller.js"), this.buildUiController(), "utf-8"),
+			writeFile(path.join(appDirectory, "assets", "icon.svg"), this.buildIconSvg(), "utf-8")
+		]);
+		return {
+			appDirectory,
+			manifestPath
+		};
+	};
+	assertTargetDoesNotExist = async (targetDirectory) => {
+		try {
+			await access(targetDirectory);
+		} catch {
+			return;
+		}
+		throw new Error(`目标目录已存在：${targetDirectory}`);
+	};
+	buildAppId = (targetDirectory) => {
+		return `nextclaw.${this.normalizeSlug(path.basename(targetDirectory))}`;
+	};
+	buildAppName = (targetDirectory) => {
+		return this.normalizeSlug(path.basename(targetDirectory)).split("-").map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join(" ");
+	};
+	normalizeSlug = (value) => {
+		const normalized = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+		if (!normalized) throw new Error("应用目录名无法生成合法的应用标识。");
+		return normalized;
+	};
+	buildManifest = (appId, appName) => {
+		return {
+			schemaVersion: 1,
+			id: appId,
+			name: appName,
+			version: "0.1.0",
+			description: "A minimal NextClaw micro app scaffold created by napp.",
+			icon: "assets/icon.svg",
+			main: {
+				kind: "wasm",
+				entry: "main/app.wasm",
+				export: "summarize_notes",
+				action: "runStarterDemo"
+			},
+			ui: { entry: "ui/index.html" },
+			permissions: {
+				storage: { namespace: appId.replace(/\./g, "-") },
+				capabilities: { hostBridge: true }
+			}
+		};
+	};
+	buildWatSource = () => {
+		return `(module
+  (func (export "summarize_notes") (param i32 i32) (result i32)
+    local.get 0
+    local.get 1
+    i32.add
+    i32.const 200
+    i32.add))\n`;
+	};
+	buildUiHtml = (appName) => {
+		return `<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${appName}</title>
+    <style>
+      :root {
+        color-scheme: light;
+        font-family: "IBM Plex Sans", "Helvetica Neue", sans-serif;
+        background:
+          radial-gradient(circle at top left, rgba(255, 206, 134, 0.24), transparent 30%),
+          linear-gradient(165deg, #f7f1e7 0%, #fcfcfe 48%, #e1ebf5 100%);
+        color: #11233a;
+      }
+
+      body {
+        margin: 0;
+        min-height: 100vh;
+      }
+
+      main {
+        box-sizing: border-box;
+        max-width: 760px;
+        margin: 0 auto;
+        padding: 48px 20px 72px;
+      }
+
+      .panel {
+        background: rgba(255, 255, 255, 0.78);
+        border: 1px solid rgba(17, 35, 58, 0.08);
+        border-radius: 24px;
+        box-shadow: 0 18px 42px rgba(17, 35, 58, 0.12);
+        padding: 28px;
+        backdrop-filter: blur(18px);
+      }
+
+      h1 {
+        margin: 0 0 12px;
+        font-size: clamp(30px, 6vw, 54px);
+        line-height: 1;
+      }
+
+      p {
+        line-height: 1.6;
+      }
+
+      button {
+        border: 0;
+        border-radius: 999px;
+        background: #11233a;
+        color: #fff;
+        padding: 12px 18px;
+        font-size: 15px;
+        cursor: pointer;
+      }
+
+      dl {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+        gap: 12px;
+        margin: 24px 0 0;
+      }
+
+      dt {
+        font-size: 12px;
+        color: #556881;
+        text-transform: uppercase;
+        letter-spacing: 0.08em;
+      }
+
+      dd {
+        margin: 6px 0 0;
+        font-size: 24px;
+        font-weight: 600;
+      }
+
+      pre {
+        margin-top: 20px;
+        padding: 14px;
+        border-radius: 16px;
+        background: rgba(17, 35, 58, 0.07);
+        overflow: auto;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <section class="panel">
+        <p>NextClaw Micro App</p>
+        <h1 id="title">Loading...</h1>
+        <p id="description">A starter scaffold created by napp create.</p>
+        <button id="run-button" type="button">Run Starter Demo</button>
+        <dl>
+          <div>
+            <dt>Action</dt>
+            <dd id="action">-</dd>
+          </div>
+          <div>
+            <dt>Documents</dt>
+            <dd id="document-count">-</dd>
+          </div>
+          <div>
+            <dt>Text Bytes</dt>
+            <dd id="text-bytes">-</dd>
+          </div>
+          <div>
+            <dt>Wasm Score</dt>
+            <dd id="wasm-score">-</dd>
+          </div>
+        </dl>
+        <pre id="details"></pre>
+      </section>
+    </main>
+    <script type="module" src="./app.controller.js"><\/script>
+  </body>
+</html>
+`;
+	};
+	buildUiController = () => {
+		return `const titleNode = document.getElementById("title");
+const descriptionNode = document.getElementById("description");
+const actionNode = document.getElementById("action");
+const documentCountNode = document.getElementById("document-count");
+const textBytesNode = document.getElementById("text-bytes");
+const wasmScoreNode = document.getElementById("wasm-score");
+const detailsNode = document.getElementById("details");
+const runButton = document.getElementById("run-button");
+
+const setDetails = (value) => {
+  detailsNode.textContent = JSON.stringify(value, null, 2);
+};
+
+const loadManifest = async () => {
+  const response = await fetch("/__napp/manifest");
+  const payload = await response.json();
+  titleNode.textContent = payload.manifest.name;
+  descriptionNode.textContent = payload.manifest.description;
+  actionNode.textContent = payload.manifest.main.action;
+  setDetails(payload);
+};
+
+const runDemo = async () => {
+  runButton.disabled = true;
+  try {
+    const response = await fetch("/__napp/run", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        action: actionNode.textContent,
+      }),
+    });
+    const payload = await response.json();
+    documentCountNode.textContent = String(payload.result.input.documentCount);
+    textBytesNode.textContent = String(payload.result.input.textBytes);
+    wasmScoreNode.textContent = String(payload.result.output.output);
+    setDetails(payload);
+  } finally {
+    runButton.disabled = false;
+  }
+};
+
+runButton.addEventListener("click", () => {
+  void runDemo();
+});
+
+await loadManifest();
+`;
+	};
+	buildIconSvg = () => {
+		return `<svg width="160" height="160" viewBox="0 0 160 160" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="160" height="160" rx="40" fill="#11233A" />
+  <path d="M42 45H118V58H74V115H58V58H42V45Z" fill="#F8C97E" />
+  <path d="M92 74H118V87H92V74Z" fill="#FFFFFF" fill-opacity="0.92" />
+  <path d="M92 95H118V108H92V95Z" fill="#FFFFFF" fill-opacity="0.72" />
+</svg>
+`;
+	};
+};
+const APP_WASM_BASE64 = "AGFzbQEAAAABBwFgAn9/AX8DAgEABxMBD3N1bW1hcml6ZV9ub3RlcwAACg0BCwAgACABakHIAWoL";
+//#endregion
+export { AppScaffoldService };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/app-runtime",
-  "version": "0.1.0",
+  "version": "0.3.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",