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

package/src/toolchain/source-discovery.js

@@ -0,0 +1,919 @@
+import { frontendPoint } from '../client/points.generated.js';
+import { sdkIconNames } from '../ui/icons.generated.js';
+import { readdir, readFile } from "node:fs/promises";
+import { posix, relative, resolve, sep } from "node:path";
+import ts from "typescript";
+
+import { ZhikeCliError } from "../errors.js";
+import { discoverWorkflowBlock } from "./workflow-blocks/discovery.js";
+import { assertAllowedPackageImport } from "./dependency-policy.js";
+
+const KEY_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+const RECORD_OBJECT_PATTERN = /^[a-z][a-z0-9_]{0,106}$/;
+const RECORD_EXTENSION_OBJECT_PATTERN = /^(?:accounts|contacts|opportunities|custom_[a-z0-9_]{1,100})$/;
+const RECORD_ACTION_LABEL_MAX_LENGTH = 80;
+const RECORD_ACTION_OBJECTS_MAX_LENGTH = 32;
+const RECORD_ACTION_TYPES = new Set(["record-action", "object-action", "bulk-record-action"]);
+const RECORD_COMPONENT_TYPES = new Set(["record-widget", "record-section", "record-tab"]);
+const PAGE_NAME_MAX_LENGTH = 80;
+const PAGE_VARIANTS = new Set(["full", "centered"]);
+const SDK_ICON_NAMES = new Set(sdkIconNames);
+const SERVER_MODULE_PATTERN = /^server\/functions\/[a-z0-9][a-z0-9/-]*$/;
+const LIFECYCLE_EVENTS = new Set([
+  "app-installed",
+  "app-uninstalled",
+  "connection-added",
+  "connection-removed",
+]);
+
+export async function discoverAppSources(projectDirectory) {
+  const sourceRoot = resolve(projectDirectory, "src");
+  const files = await listFiles(sourceRoot);
+  const normalized = files.map((path) => ({
+    absolutePath: path,
+    relativePath: relative(sourceRoot, path).split(sep).join("/"),
+  }));
+  rejectUnsupportedPaths(normalized);
+
+  const parsedFiles = [];
+  for (const file of normalized) {
+    const sourceText = await readFile(file.absolutePath, "utf8");
+    const sourceFile = ts.createSourceFile(
+      file.relativePath,
+      sourceText,
+      ts.ScriptTarget.ES2022,
+      true,
+      file.relativePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    );
+    assertSyntacticallyValid(sourceFile);
+    parsedFiles.push({ ...file, sourceFile });
+  }
+  const sourceFilesByPath = new Map(parsedFiles.map(file => [file.relativePath, file.sourceFile]));
+
+  const frontendExtensions = [];
+  const lifecycleEvents = [];
+  const serverFunctions = [];
+  const webhookHandlers = [];
+  const workflowSteps = [];
+  const workflowTriggers = [];
+  const globalKeys = new Map();
+  for (const file of parsedFiles) {
+    const { sourceFile } = file;
+    validateImports(sourceFile, file.relativePath);
+
+    const extensionMatch = file.relativePath.match(
+      /^app\/extensions\/([a-z][a-z0-9-]{0,63})\/extension\.tsx$/,
+    );
+    const pageMatch = file.relativePath.match(
+      /^app\/pages\/([a-z][a-z0-9-]{0,63})\/page\.tsx$/,
+    );
+    const lifecycleMatch = file.relativePath.match(
+      /^app\/events\/(app-installed|app-uninstalled|connection-added|connection-removed)\.event\.ts$/,
+    );
+    const webhookMatch = file.relativePath.match(
+      /^app\/webhooks\/([a-z][a-z0-9-]{0,63})\.webhook\.ts$/,
+    );
+    const serverMatch = file.relativePath.match(
+      /^(server\/functions\/[a-z0-9][a-z0-9/-]*)\.server\.ts$/,
+    );
+    const workflowBlockMatch = file.relativePath.match(
+      /^app\/blocks\/([a-z][a-z0-9-]{0,63})\/block\.ts$/,
+    );
+    if (lifecycleMatch) {
+      const definition = parseLifecycleEvent(
+        sourceFile,
+        file.relativePath,
+        lifecycleMatch[1],
+      );
+      registerUniqueKey(globalKeys, definition.key, file.relativePath);
+      lifecycleEvents.push(definition);
+    } else if (pageMatch) {
+      const definition = parseWorkspacePage(
+        sourceFile,
+        file.relativePath,
+        pageMatch[1],
+      );
+      registerUniqueKey(globalKeys, definition.key, file.relativePath);
+      frontendExtensions.push(definition);
+    } else if (extensionMatch) {
+      const definition = parseFrontendExtension(
+        sourceFile,
+        file.relativePath,
+        extensionMatch[1],
+      );
+      registerUniqueKey(globalKeys, definition.key, file.relativePath);
+      frontendExtensions.push(definition);
+    } else if (webhookMatch) {
+      const definition = parseWebhookHandler(
+        sourceFile,
+        file.relativePath,
+        webhookMatch[1],
+      );
+      registerUniqueKey(globalKeys, definition.key, file.relativePath);
+      webhookHandlers.push(definition);
+    } else if (serverMatch) {
+      const definition = parseServerFunction(
+        sourceFile,
+        file.relativePath,
+        serverMatch[1],
+      );
+      registerUniqueKey(globalKeys, definition.key, file.relativePath);
+      serverFunctions.push(definition);
+    } else if (workflowBlockMatch) {
+      const definition = discoverWorkflowBlock(
+        sourceFile, file.relativePath, workflowBlockMatch[1], sourceFilesByPath,
+      );
+      if (definition.type === "step") {
+        registerUniqueKey(globalKeys, definition.entry, file.relativePath);
+        workflowSteps.push(definition);
+      } else {
+        for (const entry of Object.values(definition.entries)) registerUniqueKey(globalKeys, entry, file.relativePath);
+        workflowTriggers.push(definition);
+      }
+    }
+  }
+  if (
+    frontendExtensions.length === 0 &&
+    lifecycleEvents.length === 0 &&
+    serverFunctions.length === 0 &&
+    webhookHandlers.length === 0 &&
+    workflowSteps.length === 0 &&
+    workflowTriggers.length === 0
+  ) {
+    throw toolchainError(
+      "zhike_source_entry_missing",
+      "未发现 Lifecycle Event、Frontend Extension、Server Function、Webhook Handler 或 Workflow Block",
+    );
+  }
+  if (frontendExtensions.filter(item => item.type === "settings").length > 1) {
+    throw toolchainError("zhike_settings_duplicate", "一个 App 至多声明一个 Settings");
+  }
+  return Object.freeze({
+    frontendExtensions: Object.freeze(sortByKey(frontendExtensions)),
+    lifecycleEvents: Object.freeze(sortByKey(lifecycleEvents)),
+    serverFunctions: Object.freeze(sortByKey(serverFunctions)),
+    sourceFiles: Object.freeze(parsedFiles.map((file) => file.relativePath).sort()),
+    webhookHandlers: Object.freeze(sortByKey(webhookHandlers)),
+    workflowSteps: Object.freeze(sortByKey(workflowSteps)),
+    workflowTriggers: Object.freeze(sortByKey(workflowTriggers)),
+  });
+}
+
+function parseLifecycleEvent(sourceFile, relativePath, fileEvent) {
+  if (hasSdkNamedImport(sourceFile, "@77-zhike/app-sdk/server", "defineLifecycleEvent")) {
+    throw toolchainError(
+      "zhike_lifecycle_event_wrapper_deprecated",
+      `${relativePath}: defineLifecycleEvent 已不再用于新 Build，请直接 default export async function`,
+    );
+  }
+  const handler = requireDefaultAsyncFunction(sourceFile, relativePath);
+  if (!LIFECYCLE_EVENTS.has(fileEvent)) {
+    throw toolchainError(
+      "zhike_lifecycle_event_identity_invalid",
+      `${relativePath}: 文件名必须是受支持的生命周期事件`,
+    );
+  }
+  return Object.freeze({ event: fileEvent, key: fileEvent, relativePath, handler });
+}
+
+function requireDefaultAsyncFunction(
+  sourceFile,
+  relativePath,
+  {
+    errorCode = "zhike_lifecycle_event_export_invalid",
+    entryName = "Lifecycle Event",
+  } = {},
+) {
+  const functions = sourceFile.statements.filter(
+    (statement) =>
+      ts.isFunctionDeclaration(statement) &&
+      statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) &&
+      statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword),
+  );
+  const defaultAssignments = sourceFile.statements.filter(
+    (statement) => ts.isExportAssignment(statement) && !statement.isExportEquals,
+  );
+  if (functions.length !== 1 || defaultAssignments.length !== 0) {
+    throw toolchainError(
+      errorCode,
+      `${relativePath}: 必须有且只有一个 export default async function`,
+    );
+  }
+  const handler = functions[0];
+  if (
+    !handler.body ||
+    !handler.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword)
+  ) {
+    throw toolchainError(
+      errorCode,
+      `${relativePath}: ${entryName} default export 必须是 async function`,
+    );
+  }
+  return handler.name?.text || null;
+}
+
+function parseFrontendExtension(sourceFile, relativePath, directoryKey) {
+  requireSdkNamedImport(
+    sourceFile,
+    relativePath,
+    "@77-zhike/app-sdk/client",
+    "defineFrontendExtension",
+  );
+  const call = requireDefaultExportCall(
+    sourceFile,
+    relativePath,
+    "defineFrontendExtension",
+  );
+  const object = requireObjectLiteral(call.arguments[0], relativePath);
+  const key = requireStringProperty(object, "key", relativePath);
+  const type = requireStringProperty(object, "type", relativePath);
+  const point = frontendPoint(type);
+  if (!point || type === "page") throw toolchainError("zhike_frontend_extension_type_unsupported", `${relativePath}: 扩展类型尚未开放`);
+  const handlerName = point.kind === "view" ? (point.componentName || "component") : (point.callbackName || "handler");
+  const forbiddenNames = point.kind === "view"
+    ? ["component", "Widget", "Section", "Tab", "Page", "handler", "onTrigger"].filter(name => name !== handlerName)
+    : ["component", "Widget", "Section", "Tab", "Page", ...(handlerName === "handler" ? ["onTrigger"] : ["handler"])];
+  if (forbiddenNames.some(name => findProperty(object, name))) {
+    throw toolchainError("zhike_frontend_definition_mixed", `${relativePath}: component 与 handler 不得混填`);
+  }
+  const property = findProperty(object, handlerName);
+  if (
+    point.kind === "view" &&
+    property &&
+    ((ts.isPropertyAssignment(property) && ts.isIdentifier(property.initializer)) ||
+      ts.isShorthandPropertyAssignment(property))
+  ) {
+    // 引用的组件由 TypeScript 检查可调用性；控制面不执行组件。
+  } else {
+    requireFunctionProperty(object, handlerName, relativePath);
+  }
+  if (key !== directoryKey || !KEY_PATTERN.test(key)) {
+    throw toolchainError(
+      "zhike_frontend_extension_key_invalid",
+      `${relativePath}: key 必须与扩展目录一致`,
+    );
+  }
+  if (RECORD_ACTION_TYPES.has(type)) {
+    return Object.freeze({
+      key,
+      type,
+      entry: key,
+      relativePath,
+      ...parseRecordActionMetadata(object, relativePath),
+    });
+  }
+  if (RECORD_COMPONENT_TYPES.has(type)) {
+    return Object.freeze({
+      key,
+      type,
+      entry: key,
+      relativePath,
+      ...parseRecordComponentMetadata(object, relativePath, handlerName),
+    });
+  }
+  return Object.freeze({ key, type, entry: key, relativePath });
+}
+
+function parseWorkspacePage(sourceFile, relativePath, slug) {
+  requireSdkNamedImport(
+    sourceFile,
+    relativePath,
+    "@77-zhike/app-sdk/client",
+    "definePage",
+  );
+  const call = requireDefaultExportCall(sourceFile, relativePath, "definePage");
+  const object = requireObjectLiteral(call.arguments[0], relativePath);
+  assertOnlyProperties(
+    object,
+    ["name", "order", "variant", "Page", "showInNavigation", "showHeader"],
+    relativePath,
+    "zhike_page_definition_invalid",
+    "Page definition 包含不支持的字段",
+  );
+
+  const rawName = requireStringProperty(object, "name", relativePath);
+  const name = rawName.trim();
+  if (
+    [...name].length === 0 ||
+    [...name].length > PAGE_NAME_MAX_LENGTH ||
+    /\p{Cc}/u.test(name)
+  ) {
+    throw toolchainError(
+      "zhike_page_name_invalid",
+      `${relativePath}: name trim 后必须是 1～${PAGE_NAME_MAX_LENGTH} 个非控制字符`,
+    );
+  }
+  const variant = requireStringProperty(object, "variant", relativePath);
+  if (!PAGE_VARIANTS.has(variant)) {
+    throw toolchainError(
+      "zhike_page_variant_invalid",
+      `${relativePath}: variant 必须是 full 或 centered`,
+    );
+  }
+  const orderProperty = findProperty(object, "order");
+  const order = orderProperty === undefined
+    ? undefined
+    : requireSafeIntegerProperty(orderProperty, relativePath);
+  const visibilityProperty = findProperty(object, "showInNavigation");
+  let showInNavigation;
+  if (visibilityProperty !== undefined) {
+    if (!ts.isPropertyAssignment(visibilityProperty)
+      || ![ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(visibilityProperty.initializer.kind)) {
+      throw toolchainError("zhike_page_visibility_invalid", `${relativePath}: showInNavigation 必须是静态布尔值`);
+    }
+    showInNavigation = visibilityProperty.initializer.kind === ts.SyntaxKind.TrueKeyword;
+  }
+  const headerProperty = findProperty(object, "showHeader");
+  let showHeader;
+  if (headerProperty !== undefined) {
+    if (!ts.isPropertyAssignment(headerProperty)
+      || ![ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(headerProperty.initializer.kind)) {
+      throw toolchainError("zhike_page_header_invalid", `${relativePath}: showHeader 必须是静态布尔值`);
+    }
+    showHeader = headerProperty.initializer.kind === ts.SyntaxKind.TrueKeyword;
+  }
+  const pageProperty = findProperty(object, "Page");
+  if (
+    !pageProperty ||
+    !ts.isPropertyAssignment(pageProperty) ||
+    !(ts.isIdentifier(pageProperty.initializer) || isFunctionLike(pageProperty.initializer))
+  ) {
+    throw toolchainError(
+      "zhike_page_component_invalid",
+      `${relativePath}: Page 必须是 React component 标识符或函数`,
+    );
+  }
+  return Object.freeze({
+    key: slug,
+    type: "page",
+    entry: slug,
+    relativePath,
+    name,
+    ...(order === undefined ? {} : { order }),
+    ...(showInNavigation === undefined ? {} : { showInNavigation }),
+    ...(showHeader === undefined ? {} : { showHeader }),
+    variant,
+  });
+}
+
+function parseRecordActionMetadata(object, relativePath) {
+  assertOnlyProperties(object, ["key", "type", "label", "icon", "objects", "onTrigger"], relativePath);
+  const label = requireStringProperty(object, "label", relativePath).trim();
+  if (
+    [...label].length === 0 ||
+    [...label].length > RECORD_ACTION_LABEL_MAX_LENGTH ||
+    /\p{Cc}/u.test(label)
+  ) {
+    throw toolchainError(
+      "zhike_record_action_label_invalid",
+      `${relativePath}: label 必须是 1～${RECORD_ACTION_LABEL_MAX_LENGTH} 个非控制字符`,
+    );
+  }
+  const iconProperty = findProperty(object, "icon");
+  const icon = iconProperty ? requireStringProperty(object, "icon", relativePath) : null;
+  if (icon !== null && (!KEY_PATTERN.test(icon) || !SDK_ICON_NAMES.has(icon))) {
+    throw toolchainError(
+      "zhike_record_action_icon_invalid",
+      `${relativePath}: icon 必须来自 SDK 统一图标目录`,
+    );
+  }
+  const objectsProperty = findProperty(object, "objects");
+  const objects = objectsProperty ? requireRecordObjects(objectsProperty, relativePath) : null;
+  return {
+    label,
+    ...(icon === null ? {} : { icon }),
+    ...(objects === null ? {} : { objects }),
+  };
+}
+
+function parseRecordComponentMetadata(object, relativePath, componentName) {
+  assertOnlyProperties(
+    object,
+    ["key", "type", "label", "objects", componentName],
+    relativePath,
+    "zhike_record_component_definition_invalid",
+    "Record Page component definition 包含不支持的字段",
+  );
+  const label = requireStringProperty(object, "label", relativePath).trim();
+  if (
+    [...label].length === 0 ||
+    [...label].length > RECORD_ACTION_LABEL_MAX_LENGTH ||
+    /\p{Cc}/u.test(label)
+  ) {
+    throw toolchainError(
+      "zhike_record_component_label_invalid",
+      `${relativePath}: label 必须是 1～${RECORD_ACTION_LABEL_MAX_LENGTH} 个非控制字符`,
+    );
+  }
+  const objectsProperty = findProperty(object, "objects");
+  const objects = objectsProperty
+    ? requireRecordObjects(
+        objectsProperty,
+        relativePath,
+        "zhike_record_component_objects_invalid",
+        true,
+      )
+    : null;
+  return {
+    label,
+    ...(objects === null ? {} : { objects }),
+  };
+}
+
+function requireRecordObjects(
+  property,
+  relativePath,
+  errorCode = "zhike_record_action_objects_invalid",
+  rejectDuplicates = false,
+) {
+  if (!ts.isPropertyAssignment(property)) {
+    throw toolchainError(errorCode, `${relativePath}: objects 必须是字符串字面量或字符串字面量数组`);
+  }
+  const initializer = property.initializer;
+  const values = ts.isStringLiteral(initializer)
+    ? [initializer.text]
+    : ts.isArrayLiteralExpression(initializer)
+      ? initializer.elements.map(item => {
+          if (!ts.isStringLiteral(item)) {
+            throw toolchainError(errorCode, `${relativePath}: objects 必须是字符串字面量数组`);
+          }
+          return item.text;
+        })
+      : null;
+  if (
+    values === null ||
+    values.length === 0 ||
+    values.length > RECORD_ACTION_OBJECTS_MAX_LENGTH ||
+    (rejectDuplicates && new Set(values).size !== values.length) ||
+    values.some(value => !RECORD_OBJECT_PATTERN.test(value) || !RECORD_EXTENSION_OBJECT_PATTERN.test(value))
+  ) {
+    throw toolchainError(
+      errorCode,
+      `${relativePath}: objects 只支持 accounts、contacts、opportunities 或 custom_*，且必须包含 1～${RECORD_ACTION_OBJECTS_MAX_LENGTH} 个合法公开对象标识`,
+    );
+  }
+  return Object.freeze(rejectDuplicates ? values : [...new Set(values)]);
+}
+
+function assertOnlyProperties(
+  object,
+  allowed,
+  relativePath,
+  code = "zhike_frontend_definition_unknown_property",
+  message = "Frontend Extension 包含不支持的字段",
+) {
+  const allowedNames = new Set(allowed);
+  for (const property of object.properties) {
+    const name = property.name && (
+      ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)
+    ) ? property.name.text : null;
+    if (!name || !allowedNames.has(name)) {
+      throw toolchainError(
+        code,
+        `${relativePath}: ${message}`,
+      );
+    }
+  }
+}
+
+function parseServerFunction(sourceFile, relativePath, moduleId) {
+  if (hasSdkNamedImport(sourceFile, "@77-zhike/app-sdk/server", "defineServerFunction")) {
+    throw toolchainError(
+      "zhike_server_function_wrapper_deprecated",
+      `${relativePath}: defineServerFunction 已不再用于新 Build，请直接 export default async function`,
+    );
+  }
+  requireDefaultAsyncFunction(sourceFile, relativePath, {
+    errorCode: "zhike_server_function_export_invalid",
+    entryName: "Server Function",
+  });
+  if (!SERVER_MODULE_PATTERN.test(moduleId)) {
+    throw toolchainError(
+      "zhike_server_function_key_invalid",
+      `${relativePath}: Server Function module ID 不合法`,
+    );
+  }
+  return Object.freeze({ key: moduleId, relativePath });
+}
+
+function parseWebhookHandler(sourceFile, relativePath, fileKey) {
+  if (hasSdkNamedImport(sourceFile, "@77-zhike/app-sdk/server", "defineWebhookHandler")) {
+    throw toolchainError(
+      "zhike_webhook_handler_wrapper_deprecated",
+      `${relativePath}: defineWebhookHandler 已不再用于新 Build，请直接 default export async function`,
+    );
+  }
+  requireDefaultAsyncFunction(sourceFile, relativePath, {
+    errorCode: "zhike_webhook_handler_export_invalid",
+    entryName: "Webhook Handler",
+  });
+  return Object.freeze({
+    key: fileKey,
+    methods: Object.freeze(["POST"]),
+    relativePath,
+  });
+}
+
+function requireDefaultExportCall(sourceFile, relativePath, expectedCallee) {
+  const exports = sourceFile.statements.filter(
+    (statement) => ts.isExportAssignment(statement) && !statement.isExportEquals,
+  );
+  if (exports.length !== 1 || !ts.isCallExpression(exports[0].expression)) {
+    throw toolchainError(
+      "zhike_entry_default_export_invalid",
+      `${relativePath}: 必须有且只有一个直接 default export`,
+    );
+  }
+  const call = exports[0].expression;
+  if (!ts.isIdentifier(call.expression) || call.expression.text !== expectedCallee) {
+    throw toolchainError(
+      "zhike_entry_definition_invalid",
+      `${relativePath}: default export 必须直接调用 ${expectedCallee}`,
+    );
+  }
+  return call;
+}
+
+function requireSdkNamedImport(sourceFile, relativePath, specifier, importedName) {
+  const matches = sourceFile.statements.filter((statement) =>
+    hasNamedImport(statement, specifier, importedName),
+  );
+  if (matches.length !== 1) {
+    throw toolchainError(
+      "zhike_sdk_definition_import_invalid",
+      `${relativePath}: ${importedName} 必须从 ${specifier} 直接 named import且不得重命名`,
+    );
+  }
+}
+
+function hasSdkNamedImport(sourceFile, specifier, importedName) {
+  return sourceFile.statements.some((statement) =>
+    hasNamedImport(statement, specifier, importedName),
+  );
+}
+
+function hasNamedImport(statement, specifier, importedName) {
+    if (
+      !ts.isImportDeclaration(statement) ||
+      statement.moduleSpecifier.text !== specifier ||
+      !statement.importClause?.namedBindings ||
+      !ts.isNamedImports(statement.importClause.namedBindings)
+    ) {
+      return false;
+    }
+    return statement.importClause.namedBindings.elements.some(
+      (element) =>
+        (element.propertyName?.text || element.name.text) === importedName &&
+        element.name.text === importedName,
+    );
+}
+
+export function validateImports(sourceFile, relativePath, options = {}) {
+  const allowsStandardFetch =
+    options.target === "server" || (!options.target && (
+      relativePath.startsWith("server/") ||
+      relativePath.startsWith("app/blocks/") ||
+      /^app\/events\/.+\.event\.ts$/.test(relativePath) ||
+      /^app\/webhooks\/.+\.webhook\.ts$/.test(relativePath)));
+  const target = allowsStandardFetch ? "server" : "client";
+  const visit = (node) => {
+    if (ts.isImportEqualsDeclaration(node) ||
+      (ts.isExportAssignment(node) && node.isExportEquals) ||
+      (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "require") ||
+      ((ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) &&
+        ts.isIdentifier(node.expression) && ["require", "module", "exports"].includes(node.expression.text))) {
+      throw toolchainError("zhike_commonjs_forbidden", relativePath + ": 只支持静态 ESM import/export，不支持 CommonJS");
+    }
+    if (
+      ts.isCallExpression(node) &&
+      node.expression.kind === ts.SyntaxKind.ImportKeyword
+    ) {
+      throw toolchainError(
+        "zhike_dynamic_import_forbidden",
+        `${relativePath}: 一期禁止动态 import`,
+      );
+    }
+    if (
+      !allowsStandardFetch &&
+      ts.isCallExpression(node) &&
+      ((ts.isIdentifier(node.expression) && node.expression.text === "fetch") ||
+        (ts.isPropertyAccessExpression(node.expression) &&
+          node.expression.name.text === "fetch" &&
+          ts.isIdentifier(node.expression.expression) &&
+          ["globalThis", "window", "self"].includes(
+            node.expression.expression.text,
+          )))
+    ) {
+      throw toolchainError(
+        "zhike_network_egress_forbidden",
+        `${relativePath}: 前端网络能力必须由受控 Host capability 提供`,
+      );
+    }
+    if (
+      (ts.isNewExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        ["EventSource", "WebSocket", "XMLHttpRequest"].includes(
+          node.expression.text,
+        )) ||
+      (ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        node.expression.name.text === "sendBeacon" &&
+        ts.isIdentifier(node.expression.expression) &&
+        node.expression.expression.text === "navigator")
+    ) {
+      throw toolchainError(
+        "zhike_network_egress_forbidden",
+        `${relativePath}: 一期禁止未托管的浏览器网络能力`,
+      );
+    }
+    if (
+      (ts.isIdentifier(node) &&
+        ["ZHIKE_CLIENT_SDK", "ZHIKE_SERVER_SDK"].includes(node.text)) ||
+      (ts.isPropertyAccessExpression(node) &&
+        ["ZHIKE_CLIENT_SDK", "ZHIKE_SERVER_SDK"].includes(node.name.text))
+    ) {
+      throw toolchainError(
+        "zhike_host_global_forbidden",
+        `${relativePath}: App 源码不得直接读取 Host SDK global`,
+      );
+    }
+    const moduleSpecifier = (ts.isImportDeclaration(node) || ts.isExportDeclaration(node))
+      ? node.moduleSpecifier
+      : ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)
+        ? node.argument.literal : null;
+    if (moduleSpecifier && ts.isStringLiteral(moduleSpecifier)) {
+      const specifier = moduleSpecifier.text;
+      if (specifier === "@77-zhike/app-sdk/server" && !allowsStandardFetch) {
+        throw toolchainError(
+          "zhike_server_sdk_client_forbidden",
+          `${relativePath}: 前端代码不得导入服务端 SDK`,
+        );
+      }
+      const clientTypeOnly = target === "server" && specifier === "@77-zhike/app-sdk/client"
+        && (ts.isImportTypeNode(node) || node.isTypeOnly || (ts.isImportDeclaration(node) && node.importClause?.isTypeOnly));
+      if (!specifier.startsWith(".") && !clientTypeOnly) assertAllowedPackageImport(specifier, target, relativePath);
+      if (specifier.startsWith(".") && !options.dependency) {
+        const resolvedSourcePath = posix.normalize(
+          posix.join(posix.dirname(relativePath), specifier),
+        );
+        if (resolvedSourcePath === ".." || resolvedSourcePath.startsWith("../")) {
+          throw toolchainError(
+            "zhike_source_import_outside_root",
+            `${relativePath}: relative import 不得越过 src 根目录`,
+          );
+        }
+      }
+      if (specifier.includes(".server.tsx") || specifier.endsWith(".server.tsx")) {
+        throw toolchainError(
+          "zhike_server_function_extension_invalid",
+          `${relativePath}: Server Function 不支持 .server.tsx`,
+        );
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+}
+
+function rejectUnsupportedPaths(files) {
+  for (const file of files) {
+    const path = file.relativePath;
+    if (
+      path.startsWith("app/events/") &&
+      path.endsWith(".ts") &&
+      !/^app\/events\/(app-installed|app-uninstalled|connection-added|connection-removed)\.event\.ts$/.test(path)
+    ) {
+      throw toolchainError(
+        "zhike_lifecycle_event_location_invalid",
+        `${path}: 生命周期事件文件名不受支持`,
+      );
+    }
+    if (path === "app.ts" || path === "app/index.ts") {
+      throw toolchainError(
+        "zhike_legacy_entry_forbidden",
+        `${path}: 一期不支持 Legacy app entry`,
+      );
+    }
+    if (/(^|\/)(workflows?|connections?)(\/|\.|$)/i.test(path)) {
+      throw toolchainError(
+        "zhike_capability_unsupported",
+        `${path}: 一期不支持 Workflow/Event/Connection/Settings`,
+      );
+    }
+    if (path.startsWith("server/steps/") || path.startsWith("server/triggers/")) {
+      throw toolchainError(
+        "zhike_workflow_block_location_invalid",
+        `${path}: Workflow Block 必须位于 src/app/blocks/<block-key>/`,
+      );
+    }
+    if (path.startsWith("app/blocks/") && /\.(?:ts|tsx)$/.test(path)) {
+      const validBlockFile = /^app\/blocks\/[a-z][a-z0-9-]{0,63}\/(?:block|execute|activate|trigger|deactivate)\.ts$/.test(path);
+      const helperFile = /^app\/blocks\/[a-z][a-z0-9-]{0,63}\/[-a-zA-Z0-9._]+\.ts$/.test(path) &&
+        !/\/(?:block|execute|activate|trigger|deactivate)\./.test(path);
+      if (!validBlockFile && !helperFile) {
+        throw toolchainError(
+          "zhike_workflow_block_location_invalid",
+          `${path}: Block 必须位于 src/app/blocks/<block-key>/，固定入口只允许 .ts`,
+        );
+      }
+    }
+    if (path.endsWith(".server.tsx")) {
+      throw toolchainError(
+        "zhike_server_function_extension_invalid",
+        `${path}: Server Function 只允许 .server.ts`,
+      );
+    }
+    if (
+      path.endsWith(".server.ts") &&
+      !/^server\/functions\/[a-z0-9][a-z0-9/-]*\.server\.ts$/.test(path)
+    ) {
+      throw toolchainError(
+        "zhike_server_function_location_invalid",
+        `${path}: Server Function 必须位于 src/server/functions`,
+      );
+    }
+    if (
+      path.startsWith("app/extensions/") &&
+      path.endsWith(".tsx") &&
+      !/^app\/extensions\/[a-z][a-z0-9-]{0,63}\/extension\.tsx$/.test(path)
+    ) {
+      throw toolchainError(
+        "zhike_frontend_extension_location_invalid",
+        `${path}: Frontend Extension 必须使用约定目录`,
+      );
+    }
+    if (/^app\/pages\/[^/]+\/page\.tsx$/.test(path)) {
+      const slug = path.split("/")[2];
+      if (!KEY_PATTERN.test(slug)) {
+        throw toolchainError(
+          "zhike_page_slug_invalid",
+          `${path}: Page slug 必须是最多 64 字符的 lowercase kebab-case`,
+        );
+      }
+    } else if (path.startsWith("app/pages/") && /\/page\.(?:ts|tsx)$/.test(path)) {
+      throw toolchainError(
+        "zhike_page_location_invalid",
+        `${path}: Page 必须位于 src/app/pages/<slug>/page.tsx 一级目录`,
+      );
+    }
+    if (
+      path.startsWith("app/webhooks/") &&
+      path.endsWith(".ts") &&
+      !/^app\/webhooks\/[a-z][a-z0-9-]{0,63}\.webhook\.ts$/.test(path)
+    ) {
+      throw toolchainError(
+        "zhike_webhook_location_invalid",
+        `${path}: Webhook Handler 必须使用 <key>.webhook.ts`,
+      );
+    }
+  }
+}
+
+function requireObjectLiteral(node, relativePath) {
+  if (!node || !ts.isObjectLiteralExpression(node)) {
+    throw toolchainError(
+      "zhike_entry_definition_invalid",
+      `${relativePath}: definition 必须是可静态解析的对象字面量`,
+    );
+  }
+  return node;
+}
+
+function requireStringProperty(object, name, relativePath) {
+  const property = findProperty(object, name);
+  if (!property || !ts.isPropertyAssignment(property) || !ts.isStringLiteral(property.initializer)) {
+    throw toolchainError(
+      "zhike_entry_definition_invalid",
+      `${relativePath}: ${name} 必须是字符串字面量`,
+    );
+  }
+  return property.initializer.text;
+}
+
+function requireStringArrayProperty(object, name, relativePath) {
+  const property = findProperty(object, name);
+  if (!property || !ts.isPropertyAssignment(property) || !ts.isArrayLiteralExpression(property.initializer)) {
+    throw toolchainError(
+      "zhike_entry_definition_invalid",
+      `${relativePath}: ${name} 必须是字符串字面量数组`,
+    );
+  }
+  return property.initializer.elements.map((item) => {
+    if (!ts.isStringLiteral(item)) {
+      throw toolchainError(
+        "zhike_entry_definition_invalid",
+        `${relativePath}: ${name} 必须是字符串字面量数组`,
+      );
+    }
+    return item.text.toUpperCase();
+  });
+}
+
+function requireSafeIntegerProperty(property, relativePath) {
+  if (!ts.isPropertyAssignment(property)) {
+    throw toolchainError(
+      "zhike_page_order_invalid",
+      `${relativePath}: order 必须是安全整数字面量`,
+    );
+  }
+  const initializer = property.initializer;
+  const value = ts.isNumericLiteral(initializer)
+    ? Number(initializer.text)
+    : ts.isPrefixUnaryExpression(initializer) &&
+        initializer.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(initializer.operand)
+      ? -Number(initializer.operand.text)
+      : Number.NaN;
+  if (!Number.isSafeInteger(value)) {
+    throw toolchainError(
+      "zhike_page_order_invalid",
+      `${relativePath}: order 必须是安全整数字面量`,
+    );
+  }
+  return value;
+}
+
+function requireFunctionProperty(object, name, relativePath, { requireAsync = false } = {}) {
+  const property = findProperty(object, name);
+  const functionNode =
+    property && ts.isMethodDeclaration(property)
+      ? property
+      : property && ts.isPropertyAssignment(property) && isFunctionLike(property.initializer)
+        ? property.initializer
+        : null;
+  if (
+    !functionNode ||
+    (requireAsync &&
+      !functionNode.modifiers?.some(
+        (modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword,
+      ))
+  ) {
+    throw toolchainError(
+      "zhike_entry_definition_invalid",
+      `${relativePath}: ${name} 必须是${requireAsync ? " async" : ""}函数`,
+    );
+  }
+  return functionNode;
+}
+
+function findProperty(object, name) {
+  return object.properties.find((property) => {
+    const propertyName = property.name;
+    return (
+      (ts.isIdentifier(propertyName) || ts.isStringLiteral(propertyName)) &&
+      propertyName.text === name
+    );
+  });
+}
+
+function isFunctionLike(node) {
+  return ts.isArrowFunction(node) || ts.isFunctionExpression(node);
+}
+
+function registerUniqueKey(keys, key, relativePath) {
+  const existing = keys.get(key);
+  if (existing) {
+    throw toolchainError(
+      "zhike_definition_key_duplicate",
+      `definition key ${key} 同时出现在 ${existing} 和 ${relativePath}`,
+    );
+  }
+  keys.set(key, relativePath);
+}
+
+function assertSyntacticallyValid(sourceFile) {
+  if (sourceFile.parseDiagnostics.length === 0) return;
+  const diagnostic = sourceFile.parseDiagnostics[0];
+  throw toolchainError(
+    "zhike_source_syntax_invalid",
+    `${sourceFile.fileName}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")}`,
+  );
+}
+
+async function listFiles(root) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+  const result = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const path = resolve(root, entry.name);
+    if (entry.isDirectory()) {
+      result.push(...(await listFiles(path)));
+    } else if (entry.isFile() && /\.(ts|tsx)$/.test(entry.name)) {
+      result.push(path);
+    }
+  }
+  return result;
+}
+
+function sortByKey(items) {
+  return items.sort((left, right) => left.key.localeCompare(right.key));
+}
+
+function toolchainError(code, message) {
+  return new ZhikeCliError(code, message);
+}