@77-zhike/app-sdk 0.2.0-d7b1.10

package/src/toolchain/dependency-policy.js

@@ -0,0 +1,181 @@
+import { readFileSync } from "node:fs";
+import { readFile, realpath } from "node:fs/promises";
+import { builtinModules } from "node:module";
+import { dirname, extname, isAbsolute, relative, resolve, sep } from "node:path";
+import ts from "typescript";
+import { ZhikeCliError } from "../errors.js";
+
+const packages = JSON.parse(readFileSync(new URL("./allowed-packages.json", import.meta.url), "utf8"));
+export const SDK_IMPORTS = new Set([
+  "@77-zhike/app-sdk", "@77-zhike/app-sdk/client", "@77-zhike/app-sdk/ui",
+  "@77-zhike/app-sdk/jsx-runtime", "@77-zhike/app-sdk/jsx-dev-runtime",
+  "@77-zhike/app-sdk/forms", "@77-zhike/app-sdk/server",
+  "react", "react/jsx-runtime", "react/jsx-dev-runtime",
+]);
+const builtins = new Set(builtinModules.map(name => name.replace(/^node:/, "")));
+
+function fail(code, source, message) {
+  throw new ZhikeCliError(code, source + ": " + message);
+}
+
+function splitPackage(specifier) {
+  const parts = specifier.split("/");
+  const length = specifier.startsWith("@") ? 2 : 1;
+  return { name: parts.slice(0, length).join("/"),
+    subpath: parts.length === length ? "." : "./" + parts.slice(length).join("/") };
+}
+
+export function assertAllowedPackageImport(specifier, target, source) {
+  if (specifier.startsWith("node:") || builtins.has(specifier)) {
+    fail("zhike_node_builtin_forbidden", source, "禁止 Node builtin " + specifier);
+  }
+  if (SDK_IMPORTS.has(specifier)) {
+    if (target === "client" && specifier === "@77-zhike/app-sdk/server") {
+      fail("zhike_server_sdk_client_forbidden", source, "前端代码不得导入服务端 SDK");
+    }
+    if (target === "server" && specifier === "@77-zhike/app-sdk/client") {
+      fail("zhike_client_sdk_server_forbidden", source, "服务端代码不得导入客户端 SDK 运行时");
+    }
+    return null;
+  }
+  const { name, subpath } = splitPackage(specifier);
+  const policy = Object.hasOwn(packages, name) ? packages[name] : null;
+  if (!policy) fail("zhike_external_dependency_forbidden", source, "未获准依赖 " + specifier);
+  if (!policy.targets.includes(target)) {
+    fail("zhike_dependency_target_forbidden", source, "该运行端不允许导入 " + name);
+  }
+  if (!policy.subpaths.includes(subpath)) {
+    fail("zhike_dependency_subpath_forbidden", source, "未获准包入口 " + specifier);
+  }
+  return { name, policy };
+}
+
+function within(root, path) {
+  const suffix = relative(root, path);
+  return suffix === "" || (!isAbsolute(suffix) && suffix !== ".." && !suffix.startsWith(".." + sep));
+}
+
+// 构建准入规则，不执行依赖代码；最终安全与授权仍由平台沙箱保证。
+export async function createDependencyPolicyPlugin(projectDirectory, target, validateSource) {
+  const projectRoot = await realpath(projectDirectory);
+  const sourceRoot = resolve(projectRoot, "src");
+  const roots = new Map();
+  const packageInfos = new Map();
+  const label = path => relative(projectRoot, path).split(sep).join("/");
+
+  async function packageInfo(path) {
+    let directory = dirname(path);
+    while (within(projectRoot, directory)) {
+      if (packageInfos.has(directory)) return packageInfos.get(directory);
+      let bytes;
+      try { bytes = await readFile(resolve(directory, "package.json"), "utf8"); }
+      catch (error) { if (error.code !== "ENOENT") throw error; }
+      if (bytes !== undefined) {
+        let metadata;
+        try { metadata = JSON.parse(bytes); }
+        catch { fail("zhike_dependency_metadata_invalid", label(path), "包元数据不是合法 JSON"); }
+        const info = { root: directory, name: metadata.name, version: metadata.version };
+        packageInfos.set(directory, info);
+        return info;
+      }
+      const parent = dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+    fail("zhike_dependency_path_forbidden", label(path), "依赖必须位于项目内的独立 npm 包");
+  }
+
+  function owner(path) {
+    return [...roots.values()].filter(info => within(info.root, path))
+      .sort((a, b) => b.root.length - a.root.length)[0] ?? null;
+  }
+
+  async function approve(path, expectedName) {
+    if (!within(projectRoot, path)) {
+      fail("zhike_dependency_path_forbidden", "dependency", "依赖真实路径不得越过项目目录");
+    }
+    const info = await packageInfo(path);
+    if (expectedName && info.name !== expectedName) {
+      fail("zhike_dependency_path_forbidden", label(path), "实际包身份与导入包名不一致");
+    }
+    const approved = assertAllowedPackageImport(info.name ?? "", target, label(path));
+    if (!approved) fail("zhike_dependency_path_forbidden", label(path), "不得经相对路径导入平台模块");
+    if (!approved.policy.versions.includes(info.version)) {
+      fail("zhike_dependency_version_forbidden", label(path), "未获准包版本 " + info.name + "@" + info.version);
+    }
+    roots.set(info.root, info);
+    return info;
+  }
+
+  return {
+    name: "zhike-package-policy",
+    setup(buildApi) {
+      async function resolveChecked(args, expectedName) {
+        const resolved = await buildApi.resolve(args.path, { resolveDir: args.resolveDir,
+          importer: args.importer, kind: args.kind,
+          pluginData: { zhikePolicyResolution: true } });
+        if (resolved.errors.length) {
+          fail("zhike_dependency_resolution_failed", args.path, "依赖无法解析，请安装项目声明的依赖");
+        }
+        if (resolved.external || resolved.namespace !== "file") {
+          fail("zhike_dependency_path_forbidden", args.path, "白名单包必须静态合并到 Artifact");
+        }
+        const path = await realpath(resolved.path);
+        let parent = null;
+        if (args.importer) {
+          try { parent = owner(await realpath(args.importer)); }
+          catch (error) { if (error.code !== "ENOENT") throw error; } // esbuild 的虚拟入口不在磁盘上。
+        }
+        if (!expectedName && parent && !within(parent.root, path)) {
+          fail("zhike_dependency_path_forbidden", label(path), "相对依赖不得越过所属包");
+        }
+        if (expectedName || parent) await approve(path, expectedName);
+        else if (!within(sourceRoot, path)) {
+          fail("zhike_source_import_outside_root", label(path), "App relative import 不得越过 src 根目录");
+        }
+        return { path };
+      }
+
+      buildApi.onResolve({ filter: /.*/ }, async args => {
+        if (args.pluginData?.zhikePolicyResolution || args.namespace !== "file") return;
+        if (args.path.startsWith(".") || isAbsolute(args.path)) return resolveChecked(args);
+        const approved = assertAllowedPackageImport(args.path, target, args.path);
+        if (approved) return resolveChecked(args, approved.name);
+      });
+
+      buildApi.onLoad({ filter: /.*/, namespace: "file" }, async args => {
+        const path = await realpath(args.path);
+        const info = owner(path);
+        if (!info) return;
+        await approve(path, info.name);
+        const extension = extname(path);
+        if (extension === ".json") return;
+        const loaders = { ".ts": "ts", ".tsx": "tsx", ".js": "js", ".mjs": "js", ".jsx": "jsx" };
+        if (!Object.hasOwn(loaders, extension)) {
+          fail("zhike_dependency_file_unsupported", label(path), "依赖只支持静态 ESM JS/TS 和 JSON");
+        }
+        const contents = await readFile(path, "utf8");
+        const sourceFile = ts.createSourceFile(label(path), contents, ts.ScriptTarget.ES2022, true,
+          extension === ".tsx" || extension === ".jsx" ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+        validateSource(sourceFile, label(path), { target, dependency: true });
+        // 在解析优化之前逐条解析，未使用的 import 也不能隐藏未批准依赖或路径逃逸。
+        for (const statement of sourceFile.statements) {
+          const specifier = (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement))
+            && statement.moduleSpecifier;
+          if (specifier && ts.isStringLiteral(specifier)) {
+            if (target === "server" && specifier.text === "@77-zhike/app-sdk/client"
+              && (statement.isTypeOnly || (ts.isImportDeclaration(statement) && statement.importClause?.isTypeOnly))) continue;
+            if (specifier.text.startsWith(".")) await resolveChecked({ path: specifier.text,
+              resolveDir: dirname(path), importer: path, kind: "import-statement" });
+            else {
+              const approved = assertAllowedPackageImport(specifier.text, target, label(path));
+              if (approved) await resolveChecked({ path: specifier.text, resolveDir: dirname(path),
+                importer: path, kind: "import-statement" }, approved.name);
+            }
+          }
+        }
+        return { contents, loader: loaders[extension], resolveDir: dirname(path) };
+      });
+    },
+  };
+}

package/src/toolchain/index.js

@@ -0,0 +1,15 @@
+export { discoverAppSources } from "./source-discovery.js";
+export {
+  APP_BUNDLE_CONTENT_TYPE,
+  APP_BUNDLE_PACKAGE_FORMAT,
+  APP_MANIFEST_MEDIA_TYPE,
+  JAVASCRIPT_MEDIA_TYPE,
+  buildAppBundle,
+} from "./real-build.js";
+export {
+  APP_BUNDLE_ALLOWED_MEMBERS,
+  APP_BUNDLE_MEMBER_MAX_BYTES,
+  APP_BUNDLE_TAR_MAX_BYTES,
+  createTransportTar,
+  parseTransportTar,
+} from "./transport-tar.js";

package/src/toolchain/real-build.js

@@ -0,0 +1,459 @@
+import { publicComponentNames } from '../ui/components.generated.js';
+import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+import { build } from "esbuild";
+import ts from "typescript";
+
+import { serializeWebhookResponse } from "./webhook-response.js";
+
+import { TOOLING_VERSION } from "../config.js";
+import { ZhikeCliError } from "../errors.js";
+import { readProjectBinding } from "../project-binding.js";
+import { canonicalJsonBytes } from "./canonical-json.js";
+import { discoverAppSources, validateImports } from "./source-discovery.js";
+import { createDependencyPolicyPlugin } from "./dependency-policy.js";
+import { createTransportTar } from "./transport-tar.js";
+
+export const APP_BUNDLE_PACKAGE_FORMAT = "zhike.app-bundle.v1";
+export const APP_BUNDLE_CONTENT_TYPE =
+  "application/vnd.qiqizhike.app-bundle+tar";
+export const APP_MANIFEST_MEDIA_TYPE =
+  "application/vnd.qiqizhike.app-manifest+json";
+export const JAVASCRIPT_MEDIA_TYPE = "application/javascript";
+
+const SDK_SOURCE_ROOT = resolve(import.meta.dirname, "..");
+
+export async function buildAppBundle({
+  projectDirectory = process.cwd(),
+  expectedEnvironment = null,
+  writeToDist = false,
+  tarOptions = {},
+  development = false,
+} = {}) {
+  await readProjectBinding(projectDirectory, expectedEnvironment);
+  const sources = await discoverAppSources(projectDirectory);
+  let clientBytes, serverBytes;
+  try {
+    clientBytes = sources.frontendExtensions.length > 0
+      ? await buildRemoteReactClient(projectDirectory, sources, development) : null;
+    serverBytes = sources.lifecycleEvents.length > 0 ||
+      sources.serverFunctions.length > 0 ||
+      sources.webhookHandlers.length > 0 ||
+      sources.workflowSteps.length > 0 ||
+      sources.workflowTriggers.length > 0
+      ? await buildServerArtifact(projectDirectory, sources) : null;
+  } catch (error) {
+    const policyError = error.errors?.find(item => item.detail instanceof ZhikeCliError)?.detail;
+    throw policyError ?? error;
+  }
+  await assertTypeScriptProgram(projectDirectory, sources);
+  const manifest = createManifest({
+    clientBytes,
+    serverBytes,
+    sources,
+  });
+  const manifestBytes = canonicalJsonBytes(manifest);
+  const entries = [
+    { name: "manifest.json", bytes: manifestBytes },
+    ...(clientBytes ? [{ name: "client.js", bytes: clientBytes }] : []),
+    ...(serverBytes ? [{ name: "server.js", bytes: serverBytes }] : []),
+  ];
+  const tarBytes = createTransportTar(entries, tarOptions);
+  const artifacts = Object.freeze([
+    createArtifact("manifest", "manifest.json", APP_MANIFEST_MEDIA_TYPE, manifestBytes),
+    ...(clientBytes
+      ? [createArtifact("client", "client.js", JAVASCRIPT_MEDIA_TYPE, clientBytes)]
+      : []),
+    ...(serverBytes
+      ? [createArtifact("server", "server.js", JAVASCRIPT_MEDIA_TYPE, serverBytes)]
+      : []),
+  ]);
+  if (writeToDist) {
+    const distDirectory = resolve(projectDirectory, "dist");
+    await rm(distDirectory, { recursive: true, force: true });
+    await mkdir(distDirectory, { recursive: true });
+    for (const artifact of artifacts) {
+      await writeFile(resolve(distDirectory, artifact.path), artifact.bytes, {
+        flag: "wx",
+      });
+    }
+    await writeFile(resolve(distDirectory, "app-bundle.tar"), tarBytes, {
+      flag: "wx",
+    });
+  }
+  return Object.freeze({
+    artifacts,
+    bytes: tarBytes,
+    manifest: Object.freeze(manifest),
+    packageFormat: APP_BUNDLE_PACKAGE_FORMAT,
+    contentType: APP_BUNDLE_CONTENT_TYPE,
+    sha256: sha256(tarBytes),
+    size: tarBytes.byteLength,
+    toolingVersion: TOOLING_VERSION,
+  });
+}
+
+async function assertTypeScriptProgram(projectDirectory, { sourceFiles, serverFunctions }) {
+  const paths = {
+    "@77-zhike/app-sdk": [resolve(SDK_SOURCE_ROOT, "index.d.ts")],
+    "@77-zhike/app-sdk/client": [resolve(SDK_SOURCE_ROOT, "client", "index.d.ts")],
+    "@77-zhike/app-sdk/server": [resolve(SDK_SOURCE_ROOT, "server", "index.d.ts")],
+    "@77-zhike/app-sdk/ui": [resolve(SDK_SOURCE_ROOT, "ui", "index.d.ts")],
+    "@77-zhike/app-sdk/forms": [resolve(SDK_SOURCE_ROOT, "forms", "index.d.ts")],
+    "@77-zhike/app-sdk/jsx-runtime": [resolve(SDK_SOURCE_ROOT, "jsx-runtime.d.ts")],
+    "@77-zhike/app-sdk/jsx-dev-runtime": [resolve(SDK_SOURCE_ROOT, "jsx-dev-runtime.d.ts")],
+    "react": [resolve(dirname(createRequire(import.meta.url).resolve("@types/react/package.json")), "index.d.ts")],
+    "react/jsx-runtime": [resolve(dirname(createRequire(import.meta.url).resolve("@types/react/package.json")), "jsx-runtime.d.ts")],
+    "react/jsx-dev-runtime": [resolve(dirname(createRequire(import.meta.url).resolve("@types/react/package.json")), "jsx-dev-runtime.d.ts")],
+  };
+  const options = {
+    baseUrl: projectDirectory,
+    jsx: ts.JsxEmit.ReactJSX,
+    jsxImportSource: "@77-zhike/app-sdk",
+    lib: ["lib.es2022.d.ts", "lib.dom.d.ts"],
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    noEmit: true,
+    noUncheckedIndexedAccess: true,
+    paths,
+    skipLibCheck: false,
+    strict: true,
+    target: ts.ScriptTarget.ES2022,
+  };
+  const rootNames = sourceFiles.map((path) => resolve(projectDirectory, "src", path));
+  // 仅供 TypeScript 检查，不落盘、不进 Artifact；复用原包装的参数/结果合同。
+  const contractPath = resolve(projectDirectory, ".zhike/server-function-contracts.ts");
+  const contractSource = [
+    'import type { ServerFunction } from "@77-zhike/app-sdk/server";',
+    ...serverFunctions.flatMap(({ relativePath }, index) => [
+      `import handler${index} from ${JSON.stringify(`../src/${relativePath.slice(0, -3)}`)};`,
+      `type Contract${index} = ServerFunction<Parameters<typeof handler${index}>, Awaited<ReturnType<typeof handler${index}>>>;`,
+    ]),
+  ].join("\n");
+  const host = ts.createCompilerHost(options);
+  const getSourceFile = host.getSourceFile.bind(host);
+  host.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) =>
+    resolve(fileName) === contractPath
+      ? ts.createSourceFile(fileName, contractSource, languageVersion, true)
+      : getSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile);
+  if (serverFunctions.length) rootNames.push(contractPath);
+  const program = ts.createProgram({ rootNames, options, host });
+  const diagnostics = ts.getPreEmitDiagnostics(program);
+  if (diagnostics.length === 0) return;
+  const diagnostic = diagnostics[0];
+  const contractLine = diagnostic.file?.fileName === contractPath
+    ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start || 0).line : -1;
+  const contractOwner = contractLine > 0 ? serverFunctions[Math.floor((contractLine - 1) / 2)] : null;
+  const location = contractOwner ? `src/${contractOwner.relativePath}（参数/返回类型）` : diagnostic.file
+    ? `${relative(projectDirectory, diagnostic.file.fileName).split(sep).join("/")}:${
+        diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start || 0).line + 1
+      }`
+    : "TypeScript";
+  throw new ZhikeCliError(
+    "zhike_typescript_diagnostic",
+    `${location}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")}`,
+  );
+}
+
+async function buildRemoteReactClient(projectDirectory, sources, development) {
+  const imports = sources.frontendExtensions.map((item, i) =>
+    `import extension${i} from "./src/${item.relativePath}";`).join("\n");
+  const entries = sources.frontendExtensions.map((item, i) =>
+    `${JSON.stringify(item.key)}: extension${i}`).join(",");
+  const result = await build({
+    absWorkingDir: projectDirectory, bundle: true, charset: "utf8", format: "cjs",
+    legalComments: "none", logLevel: "silent", minify: true, platform: "browser",
+    external: ["@77-zhike/app-sdk/runtime", "react", "react/jsx-runtime", "react/jsx-dev-runtime", "@77-zhike/app-sdk/client", "@77-zhike/app-sdk/ui", "@77-zhike/app-sdk/forms"],
+    plugins: [createSdkBuildPlugin(projectDirectory, sources, "remote-client"),
+      await createDependencyPolicyPlugin(projectDirectory, "client", validateImports)],
+    sourcemap: development ? "inline" : false,
+    banner: { js: 'export function createClientApp(platformModules) {\nconst module = { exports: {} };\nconst exports = module.exports;\nconst require = name => { if (!Object.hasOwn(platformModules, name)) throw new Error("runtime_module_unavailable"); return platformModules[name]; };\nconst Promise = require("@77-zhike/app-sdk/runtime").Promise;' },
+    footer: { js: 'return module.exports;\n}' },
+    // dev 只增加源码映射；编译语义与正式发布一致，不能依赖宿主的 React 开发构建。
+    jsx: "automatic", jsxDev: false, jsxImportSource: "@77-zhike/app-sdk",
+    define: { "process.env.NODE_ENV": '"production"' },
+    stdin: { contents: `${imports}\nexport const extensions = Object.freeze({${entries}});`, loader: "tsx", resolveDir: projectDirectory, sourcefile: "zhike-client-entry.tsx" },
+    // 原生 await 不经过 Promise.then；降级后的 helper 必须使用工厂内受管 Promise。
+    target: "es2022", supported: { "async-await": false, "async-generator": false }, treeShaking: true, write: false,
+  });
+  const bytes = normalizeJavascriptOutput(result.outputFiles[0].contents);
+  if (bytes.byteLength > 2 * 1024 * 1024) {
+    throw new ZhikeCliError("zhike_client_too_large", "client Artifact（包含源码映射）超过 2 MiB");
+  }
+  return bytes;
+}
+
+async function buildServerArtifact(projectDirectory, sources) {
+  const hasConnectionLifecycle = sources.lifecycleEvents.some(
+    ({ event }) => event === "connection-added" || event === "connection-removed",
+  );
+  const imports = [
+    ...(hasConnectionLifecycle
+      ? ['import { getWorkspaceConnection as getLifecycleConnection } from "@77-zhike/app-sdk/server";']
+      : []),
+    ...sources.lifecycleEvents.map(
+      (definition, index) =>
+        `import lifecycleEvent${index} from "./src/${definition.relativePath}";`,
+    ),
+    ...sources.serverFunctions.map(
+      (definition, index) =>
+        `import serverFunction${index} from "./src/${definition.relativePath}";`,
+    ),
+    ...sources.webhookHandlers.map(
+      (definition, index) =>
+        `import webhookHandler${index} from "./src/${definition.relativePath}";`,
+    ),
+    ...sources.workflowSteps.map(
+      (definition, index) =>
+        `import workflowStep${index} from "./src/${definition.handlerPaths.execute}";`,
+    ),
+    ...sources.workflowTriggers.map(
+      (definition, index) => Object.entries(definition.handlerPaths).map(([name, path]) =>
+        `import workflowTrigger${index}_${name} from "./src/${path}";`).join("\n"),
+    ),
+  ].join("\n");
+  const lifecycleEntries = sources.lifecycleEvents
+    .map(
+      (definition, index) =>
+        `[${JSON.stringify(definition.key)}, { event: ${JSON.stringify(definition.event)}, handler: lifecycleEvent${index} }]`,
+    )
+    .join(",\n");
+  const serverEntries = sources.serverFunctions
+    .map(
+      (definition, index) =>
+        `[${JSON.stringify(definition.key)}, serverFunction${index}]`,
+    )
+    .join(",\n");
+  const webhookEntries = sources.webhookHandlers
+    .map(
+      (definition, index) =>
+        `[${JSON.stringify(definition.key)}, webhookHandler${index}]`,
+    )
+    .join(",\n");
+  const workflowEntries = sources.workflowSteps
+    .map((definition, index) => `[${JSON.stringify(definition.entry)}, workflowStep${index}]`)
+    .join(",\n");
+  const triggerEntries = sources.workflowTriggers.flatMap((definition, index) =>
+    Object.entries(definition.entries).map(([name, entry]) =>
+      `[${JSON.stringify(entry)}, workflowTrigger${index}_${name}]`)).join(",\n");
+  const triggerDeclarations = sources.workflowTriggers.length > 0
+    ? `const workflowTriggers = new Map([${triggerEntries}]);\n`
+    : "";
+  const triggerDispatch = sources.workflowTriggers.length > 0
+    ? `  if (request.kind === "workflow_trigger") {\n    const handler = workflowTriggers.get(request.entryKey);\n    if (!handler) throw new Error("runtime_workflow_trigger_not_found");\n    const result = await handler(Object.freeze({ ...request.params }));\n    return request.entryKey.endsWith("/deactivate") ? null : result;\n  }\n`
+    : "";
+  const stdin = `${imports}\n${serializeWebhookResponse.toString()}\nconst lifecycleEvents = new Map([${lifecycleEntries}]);\nconst serverFunctions = new Map([${serverEntries}]);\nconst webhookHandlers = new Map([${webhookEntries}]);\nconst workflowSteps = new Map([${workflowEntries}]);\n${triggerDeclarations}export async function dispatchServerInvocation(request) {\n  if (!request || typeof request !== "object") throw new Error("runtime_invocation_invalid");\n  if (request.kind === "lifecycle_event") {\n    const definition = lifecycleEvents.get(request.entryKey);\n    if (!definition) throw new Error("runtime_lifecycle_event_not_found");\n    const params = definition.event === "app-installed" || definition.event === "app-uninstalled" ? request.context : Object.freeze({ connection: getLifecycleConnection() });\n    await definition.handler(params);\n    return null;\n  }\n  if (request.kind === "server_function") {\n    const handler = serverFunctions.get(request.entryKey);\n    if (!handler) throw new Error("runtime_server_function_not_found");\n    return handler(...request.args);\n  }\n  if (request.kind === "workflow_step") {\n    const handler = workflowSteps.get(request.entryKey);\n    if (!handler) throw new Error("runtime_workflow_step_not_found");\n    return handler(Object.freeze({ config: request.config }));\n  }\n${triggerDispatch}  if (request.kind === "webhook_handler") {\n    const handler = webhookHandlers.get(request.entryKey);\n    if (!handler) throw new Error("runtime_webhook_handler_not_found");\n    const input = request.webRequest;\n    const webRequest = new Request(input.url, { method: input.method, headers: input.headers, body: ["GET", "HEAD"].includes(input.method) ? undefined : input.body });\n    const response = await handler(webRequest, Object.freeze({ ...request.context }));\n    if (!(response instanceof Response)) throw new Error("runtime_webhook_response_invalid");\n    return serializeWebhookResponse(response);\n  }\n  throw new Error("runtime_invocation_kind_invalid");\n}\n`;
+  const result = await build({
+    absWorkingDir: projectDirectory,
+    bundle: true,
+    charset: "utf8",
+    format: "esm",
+    legalComments: "none",
+    logLevel: "silent",
+    minify: true,
+    platform: "browser",
+    plugins: [createSdkBuildPlugin(projectDirectory, sources, "server"),
+      await createDependencyPolicyPlugin(projectDirectory, "server", validateImports)],
+    sourcemap: false,
+    stdin: { contents: stdin, loader: "ts", resolveDir: projectDirectory, sourcefile: "zhike-server-entry.ts" },
+    target: "es2022",
+    treeShaking: true,
+    write: false,
+  });
+  const bytes = normalizeJavascriptOutput(result.outputFiles[0].contents);
+  const definitionsDigest = createServerDefinitionsDigest(sources);
+  return Buffer.concat([
+    bytes,
+    Buffer.from(`//# zhike-server-definitions-sha256=${definitionsDigest}\n`, "utf8"),
+  ]);
+}
+
+function createSdkBuildPlugin(projectDirectory, sources, target) {
+  const serverKeys = new Set(sources.serverFunctions.map((item) => item.key));
+  return {
+    name: "zhike-app-sdk-runtime",
+    setup(buildApi) {
+      buildApi.onResolve({ filter: /^@77-zhike\/app-sdk\/jsx(?:-dev)?-runtime$/ }, args => ({ path: args.path, namespace: "zhike-jsx" }));
+      buildApi.onLoad({ filter: /.*/, namespace: "zhike-jsx" }, args => ({
+        contents: args.path.endsWith("jsx-dev-runtime")
+          ? 'export { jsxDEV, Fragment } from "react/jsx-dev-runtime";'
+          : 'export { jsx, jsxs, Fragment } from "react/jsx-runtime";', loader: "js",
+      }));
+      if (target === 'remote-client') {
+        buildApi.onResolve({ filter: /\.css\?inline$/ }, args => args.path.startsWith('.')
+          ? { path: resolve(args.resolveDir, args.path.slice(0, -7)), namespace: 'zhike-native-css' }
+          : { errors: [{ text: 'NativeDOM 样式必须使用本地相对路径' }] });
+        buildApi.onLoad({ filter: /.*/, namespace: 'zhike-native-css' }, async args => ({
+          contents: await readFile(args.path, 'utf8'), loader: 'text', watchFiles: [args.path],
+        }));
+      }
+      if (target === "remote-client") {
+        // 新构建固化 authoring 默认值；Guest 仍为不可变旧 Bundle 提供兼容模块。
+        buildApi.onResolve({ filter: /^@77-zhike\/app-sdk\/ui$/ }, args => args.namespace === "zhike-ui-authoring"
+          ? { path: args.path, external: true }
+          : { path: args.path, namespace: "zhike-ui-authoring" });
+        buildApi.onLoad({ filter: /.*/, namespace: "zhike-ui-authoring" }, () => ({ loader: "js", contents: `
+          import * as ui from "@77-zhike/app-sdk/ui";
+          import { createElement } from "react";
+          export const TextBlock = props => createElement(ui.TextBlock, { ...props, align: props.align ?? "left" });
+          export const Badge = props => {
+            if (props.tone !== undefined) throw new Error("Badge.tone 已移除，请使用 StatusBadge");
+            return createElement(ui.Badge, props);
+          };
+          export const TableCell = Object.defineProperties(props => createElement(ui.TableCell, props), { Avatar: { get: () => ui.Avatar }, Badge: { value: Badge } });
+          export const Table = Object.defineProperties(props => createElement(ui.Table, props), { Header: { get: () => ui.Table.Header }, HeaderCell: { get: () => ui.Table.HeaderCell }, Body: { get: () => ui.Table.Body }, Row: { get: () => ui.Table.Row }, Cell: { value: TableCell } });
+          export const { ${[...publicComponentNames.filter(name => !["TextBlock", "Badge", "Table", "TableCell"].includes(name)), "Typography", "Widget"].join(", ")} } = ui;
+        ` }));
+      }
+      if (target !== "remote-client") buildApi.onResolve({ filter: /^@77-zhike\/app-sdk\/(client|server)$/ }, (args) => ({
+        external: target === "server" && args.path.endsWith("/server"),
+        path: args.path,
+        ...(target === "server" && args.path.endsWith("/server")
+          ? {}
+          : { namespace: "zhike-sdk-runtime" }),
+      }));
+      buildApi.onLoad({ filter: /.*/, namespace: "zhike-sdk-runtime" }, (args) => {
+        if (args.path.endsWith("/client")) {
+          return {
+            contents: "export const defineFrontendExtension = (definition) => definition; export const definePage = (definition) => ({ ...definition, type: 'page' });",
+            loader: "js",
+          };
+        }
+        return { contents: "export const defineLifecycleEvent = (definition) => definition; export const defineServerFunction = (handler) => handler; export const defineWebhookHandler = (definition) => definition; export const createWebhookHandler = async () => { throw new Error('webhook_handler_runtime_unavailable'); }; export const listWebhookHandlers = async () => { throw new Error('webhook_handler_runtime_unavailable'); }; export const deleteWebhookHandler = async () => { throw new Error('webhook_handler_runtime_unavailable'); };", loader: "js" };
+      });
+      if (target === "client" || target === "remote-client") {
+        buildApi.onResolve({ filter: /\.server(?:\.ts)?$/ }, (args) => {
+          let absolute = resolve(args.resolveDir, args.path);
+          if (!absolute.endsWith(".ts")) absolute = `${absolute}.ts`;
+          const normalizedAbsolute = absolute.split(sep).join("/");
+          const sourceMarker = "/src/";
+          const sourceIndex = normalizedAbsolute.lastIndexOf(sourceMarker);
+          const moduleId =
+            sourceIndex === -1
+              ? ""
+              : normalizedAbsolute
+                  .slice(sourceIndex + sourceMarker.length)
+                  .replace(/\.server\.ts$/, "");
+          if (!serverKeys.has(moduleId)) {
+            return { errors: [{ text: `未声明的 Server Function import：${moduleId}` }] };
+          }
+          return { path: moduleId, namespace: "zhike-server-rpc" };
+        });
+        buildApi.onLoad({ filter: /.*/, namespace: "zhike-server-rpc" }, (args) => ({
+          contents: target === "remote-client"
+            ? `const runtime = require("@77-zhike/app-sdk/runtime"); export default (...args) => runtime.invokeServerFunction(${JSON.stringify(args.path)}, args);`
+            : `export default (...args) => globalThis.ZHIKE_CLIENT_SDK.invokeServerFunction(${JSON.stringify(args.path)}, args);`,
+          loader: "js",
+        }));
+      }
+    },
+  };
+}
+
+function createManifest({ clientBytes, serverBytes, sources }) {
+  return {
+    schemaVersion: "zhike.app-manifest.v1",
+    sdkAbiVersion: "2",
+    toolchainVersion: TOOLING_VERSION,
+    ...(sources.frontendExtensions.length > 0
+      ? { clientRuntime: { runtimeVersion: "remote-react.v3" } } : {}),
+    artifacts: {
+      ...(clientBytes
+        ? {
+            client: {
+              mediaType: JAVASCRIPT_MEDIA_TYPE,
+              path: "client.js",
+              sha256: sha256(clientBytes),
+              size: clientBytes.byteLength,
+            },
+          }
+        : {}),
+      ...(serverBytes
+        ? {
+            server: {
+              mediaType: JAVASCRIPT_MEDIA_TYPE,
+              path: "server.js",
+              sha256: sha256(serverBytes),
+              size: serverBytes.byteLength,
+            },
+          }
+        : {}),
+    },
+    frontendExtensions: sources.frontendExtensions.map(({ key, type, entry, label, icon, objects, name, order, variant, showInNavigation, showHeader }) => ({
+      artifact: "client",
+      entry,
+      key,
+      type,
+      ...(label === undefined ? {} : { label }),
+      ...(icon === undefined ? {} : { icon }),
+      ...(objects === undefined ? {} : { objects }),
+      ...(name === undefined ? {} : { name }),
+      ...(order === undefined ? {} : { order }),
+      ...(variant === undefined ? {} : { variant }),
+      ...(showInNavigation === undefined ? {} : { showInNavigation }),
+      ...(showHeader === undefined ? {} : { showHeader }),
+    })),
+    lifecycleEvents: sources.lifecycleEvents.map(({ event, key }) => ({
+      artifact: "server",
+      event,
+      key,
+    })),
+    serverFunctions: sources.serverFunctions.map(({ key }) => ({
+      artifact: "server",
+      key,
+    })),
+    webhookHandlers: sources.webhookHandlers.map(({ key, methods }) => ({
+      artifact: "server",
+      key,
+      methods,
+    })),
+    ...(sources.workflowSteps.length > 0 ? { workflowSteps: sources.workflowSteps.map(
+      ({ key, title, description, connection, configSchema, outcomes, entry }) => ({
+        artifact: "server", key, entry, title,
+        ...(description === undefined ? {} : { description }),
+        connection, configSchema, outcomes,
+      }),
+    ) } : {}),
+    ...(sources.workflowTriggers.length > 0 ? { workflowTriggers: sources.workflowTriggers.map(
+      ({ key, title, description, connection, requestHeaders, configSchema, outcomes, entries }) => ({
+        artifact: "server", key, entries, title,
+        ...(description === undefined ? {} : { description }),
+        connection, requestHeaders, configSchema, outcomes,
+      }),
+    ) } : {}),
+  };
+}
+
+function createServerDefinitionsDigest(sources) {
+  return sha256(
+    canonicalJsonBytes({
+      lifecycleEvents: sources.lifecycleEvents.map(({ event, key }) => ({ event, key })),
+      serverFunctions: sources.serverFunctions.map(({ key }) => ({ key })),
+      webhookHandlers: sources.webhookHandlers.map(({ key, methods }) => ({ key, methods })),
+      ...(sources.workflowSteps.length > 0 ? { workflowSteps: sources.workflowSteps.map(({ key, entry }) => ({ key, entry })) } : {}),
+      ...(sources.workflowTriggers.length > 0 ? { workflowTriggers: sources.workflowTriggers.map(({ key, entries }) => ({ key, entries })) } : {}),
+    }),
+  );
+}
+
+function createArtifact(kind, path, mediaType, bytes) {
+  return Object.freeze({
+    bytes: Buffer.from(bytes),
+    kind,
+    mediaType,
+    path,
+    sha256: sha256(bytes),
+    size: bytes.byteLength,
+  });
+}
+
+function normalizeJavascriptOutput(bytes) {
+  const text = Buffer.from(bytes).toString("utf8").replace(/\r\n/g, "\n");
+  return Buffer.from(text.endsWith("\n") ? text : `${text}\n`, "utf8");
+}
+
+function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}