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

package/src/toolchain/real-build.js

@@ -0,0 +1,371 @@
+import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
+import { mkdir, 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 } from "./source-discovery.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);
+  await assertTypeScriptProgram(projectDirectory, sources);
+
+  const clientBytes =
+    sources.frontendExtensions.length > 0
+      ? await buildRemoteReactClient(projectDirectory, sources, development)
+      : null;
+  const serverBytes =
+    sources.lifecycleEvents.length > 0 ||
+    sources.serverFunctions.length > 0 ||
+    sources.webhookHandlers.length > 0
+      ? await buildServerArtifact(projectDirectory, sources)
+      : null;
+  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")],
+    "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,
+    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: !development, 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")],
+    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}' },
+    jsx: "automatic", jsxDev: development,
+    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}";`,
+    ),
+  ].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 stdin = `${imports}\n${serializeWebhookResponse.toString()}\nconst lifecycleEvents = new Map([${lifecycleEntries}]);\nconst serverFunctions = new Map([${serverEntries}]);\nconst webhookHandlers = new Map([${webhookEntries}]);\nexport 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 === "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")],
+    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) {
+      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;", 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.v2" } } : {}),
+    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 }) => ({
+      artifact: "client",
+      entry,
+      key,
+      type,
+      ...(label === undefined ? {} : { label }),
+      ...(icon === undefined ? {} : { icon }),
+      ...(objects === undefined ? {} : { objects }),
+    })),
+    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,
+    })),
+  };
+}
+
+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 })),
+    }),
+  );
+}
+
+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");
+}