@77-zhike/app-sdk 0.2.0-d7b1.8 → 0.2.0-d7b1.9

package/src/toolchain/dependency-policy.js

@@ -0,0 +1,175 @@
+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/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");
+    }
+    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 (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

@@ -1,11 +1,3 @@
-import { createHash } from "node:crypto";
-import { mkdir, writeFile } from "node:fs/promises";
-import { resolve } from "node:path";
-
-import { TOOLING_VERSION } from "../config.js";
-import { ZhikeCliError } from "../errors.js";
-import { readProjectBinding } from "../project-binding.js";
-
 export { discoverAppSources } from "./source-discovery.js";
 export {
   APP_BUNDLE_CONTENT_TYPE,
@@ -21,83 +13,3 @@ export {
   createTransportTar,
   parseTransportTar,
 } from "./transport-tar.js";
-
-export const MOCK_PACKAGE_FORMAT = "zhike.mock-build.v1";
-export const MOCK_ARTIFACT_KIND = "mock";
-export const MOCK_ARTIFACT_MAX_BYTES = 1024 * 1024;
-
-export async function buildMockArtifact({
-  projectDirectory = process.cwd(),
-  expectedEnvironment = null,
-  writeToDist = false,
-} = {}) {
-  await readProjectBinding(projectDirectory, expectedEnvironment);
-  const payload = {
-    format: MOCK_PACKAGE_FORMAT,
-    kind: MOCK_ARTIFACT_KIND,
-    payload: {
-      message: "qiqizhike developer app mock build",
-    },
-    toolingVersion: TOOLING_VERSION,
-  };
-  const bytes = Buffer.from(`${JSON.stringify(payload)}\n`, "utf8");
-  if (bytes.byteLength > MOCK_ARTIFACT_MAX_BYTES) {
-    throw new ZhikeCliError(
-      "zhike_mock_artifact_too_large",
-      "Mock Artifact 超过 1 MiB 上限",
-    );
-  }
-  const result = Object.freeze({
-    bytes,
-    size: bytes.byteLength,
-    sha256: createHash("sha256").update(bytes).digest("hex"),
-    packageFormat: MOCK_PACKAGE_FORMAT,
-    kind: MOCK_ARTIFACT_KIND,
-    toolingVersion: TOOLING_VERSION,
-  });
-  if (writeToDist) {
-    const distDirectory = resolve(projectDirectory, "dist");
-    await mkdir(distDirectory, { recursive: true });
-    await writeFile(resolve(distDirectory, "mock-build.json"), bytes, {
-      flag: "w",
-    });
-  }
-  return result;
-}
-
-export function validateMockArtifact(bytes) {
-  if (!Buffer.isBuffer(bytes) || bytes.byteLength > MOCK_ARTIFACT_MAX_BYTES) {
-    throw new ZhikeCliError(
-      "zhike_mock_artifact_invalid",
-      "Mock Artifact 无效或超过 1 MiB 上限",
-    );
-  }
-  let value;
-  try {
-    value = JSON.parse(bytes.toString("utf8"));
-  } catch (error) {
-    throw new ZhikeCliError(
-      "zhike_mock_artifact_invalid",
-      "Mock Artifact 不是有效 JSON",
-      { cause: error },
-    );
-  }
-  const keys = Object.keys(value).sort();
-  if (
-    keys.join(",") !== "format,kind,payload,toolingVersion" ||
-    value.format !== MOCK_PACKAGE_FORMAT ||
-    value.kind !== MOCK_ARTIFACT_KIND ||
-    value.toolingVersion !== TOOLING_VERSION ||
-    !value.payload ||
-    typeof value.payload !== "object" ||
-    Array.isArray(value.payload) ||
-    Object.keys(value.payload).join(",") !== "message" ||
-    value.payload.message !== "qiqizhike developer app mock build"
-  ) {
-    throw new ZhikeCliError(
-      "zhike_mock_artifact_invalid",
-      "Mock Artifact 不符合 zhike.mock-build.v1 严格合同",
-    );
-  }
-  return value;
-}

package/src/toolchain/real-build.js

@@ -1,4 +1,4 @@
-import { componentTypes } from '../ui/components.generated.js';
+import { publicComponentNames } from '../ui/components.generated.js';
 import { createRequire } from "node:module";
 import { createHash } from "node:crypto";
 import { mkdir, rm, writeFile } from "node:fs/promises";
@@ -12,7 +12,8 @@ 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 { 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";
@@ -33,18 +34,21 @@ export async function buildAppBundle({
 } = {}) {
   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 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,
@@ -159,7 +163,8 @@ async function buildRemoteReactClient(projectDirectory, sources, development) {
     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")],
+    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}' },
@@ -197,6 +202,14 @@ async function buildServerArtifact(projectDirectory, sources) {
       (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(
@@ -216,7 +229,19 @@ async function buildServerArtifact(projectDirectory, sources) {
         `[${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 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,
@@ -226,7 +251,8 @@ async function buildServerArtifact(projectDirectory, sources) {
     logLevel: "silent",
     minify: true,
     platform: "browser",
-    plugins: [createSdkBuildPlugin(projectDirectory, sources, "server")],
+    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",
@@ -261,7 +287,7 @@ function createSdkBuildPlugin(projectDirectory, sources, target) {
           };
           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 { ${[...componentTypes.filter(type => !["TextBlock", "Badge", "Table", "TableCell"].includes(type)), "Typography", "Widget"].join(", ")} } = ui;
+          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) => ({
@@ -365,6 +391,20 @@ function createManifest({ clientBytes, serverBytes, sources }) {
       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,
+      }),
+    ) } : {}),
   };
 }
 
@@ -374,6 +414,8 @@ function createServerDefinitionsDigest(sources) {
       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 })) } : {}),
     }),
   );
 }

package/src/toolchain/source-discovery.js

@@ -5,6 +5,8 @@ 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}$/;
@@ -23,44 +25,6 @@ const LIFECYCLE_EVENTS = new Set([
   "connection-added",
   "connection-removed",
 ]);
-const SDK_IMPORTS = new Set([
-  "@77-zhike/app-sdk",
-  "@77-zhike/app-sdk/client",
-  "@77-zhike/app-sdk/ui",
-  "@77-zhike/app-sdk/forms",
-  "react",
-  "react/jsx-runtime",
-  "react/jsx-dev-runtime",
-  "@77-zhike/app-sdk/server",
-]);
-const NODE_BUILTINS = new Set([
-  "assert",
-  "buffer",
-  "child_process",
-  "cluster",
-  "crypto",
-  "dgram",
-  "dns",
-  "events",
-  "fs",
-  "http",
-  "https",
-  "module",
-  "net",
-  "os",
-  "path",
-  "perf_hooks",
-  "process",
-  "readline",
-  "stream",
-  "tls",
-  "url",
-  "util",
-  "v8",
-  "vm",
-  "worker_threads",
-  "zlib",
-]);
 
 export async function discoverAppSources(projectDirectory) {
   const sourceRoot = resolve(projectDirectory, "src");
@@ -71,11 +35,7 @@ export async function discoverAppSources(projectDirectory) {
   }));
   rejectUnsupportedPaths(normalized);
 
-  const frontendExtensions = [];
-  const lifecycleEvents = [];
-  const serverFunctions = [];
-  const webhookHandlers = [];
-  const globalKeys = new Map();
+  const parsedFiles = [];
   for (const file of normalized) {
     const sourceText = await readFile(file.absolutePath, "utf8");
     const sourceFile = ts.createSourceFile(
@@ -86,6 +46,19 @@ export async function discoverAppSources(projectDirectory) {
       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(
@@ -103,6 +76,9 @@ export async function discoverAppSources(projectDirectory) {
     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,
@@ -143,17 +119,30 @@ export async function discoverAppSources(projectDirectory) {
       );
       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
+    webhookHandlers.length === 0 &&
+    workflowSteps.length === 0 &&
+    workflowTriggers.length === 0
   ) {
     throw toolchainError(
       "zhike_source_entry_missing",
-      "未发现一期 Lifecycle Event、Frontend Extension、Server Function 或 Webhook Handler",
+      "未发现 Lifecycle Event、Frontend Extension、Server Function、Webhook Handler 或 Workflow Block",
     );
   }
   if (frontendExtensions.filter(item => item.type === "settings").length > 1) {
@@ -163,8 +152,10 @@ export async function discoverAppSources(projectDirectory) {
     frontendExtensions: Object.freeze(sortByKey(frontendExtensions)),
     lifecycleEvents: Object.freeze(sortByKey(lifecycleEvents)),
     serverFunctions: Object.freeze(sortByKey(serverFunctions)),
-    sourceFiles: Object.freeze(normalized.map((file) => file.relativePath).sort()),
+    sourceFiles: Object.freeze(parsedFiles.map((file) => file.relativePath).sort()),
     webhookHandlers: Object.freeze(sortByKey(webhookHandlers)),
+    workflowSteps: Object.freeze(sortByKey(workflowSteps)),
+    workflowTriggers: Object.freeze(sortByKey(workflowTriggers)),
   });
 }
 
@@ -567,12 +558,22 @@ function hasNamedImport(statement, specifier, importedName) {
     );
 }
 
-function validateImports(sourceFile, relativePath) {
+export function validateImports(sourceFile, relativePath, options = {}) {
   const allowsStandardFetch =
-    relativePath.startsWith("server/") ||
-    /^app\/events\/.+\.event\.ts$/.test(relativePath) ||
-    /^app\/webhooks\/.+\.webhook\.ts$/.test(relativePath);
+    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
@@ -626,27 +627,20 @@ function validateImports(sourceFile, relativePath) {
         `${relativePath}: App 源码不得直接读取 Host SDK global`,
       );
     }
-    if (ts.isImportDeclaration(node)) {
-      const specifier = node.moduleSpecifier.text;
+    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`,
         );
       }
-      if (specifier.startsWith("node:") || NODE_BUILTINS.has(specifier)) {
-        throw toolchainError(
-          "zhike_node_builtin_forbidden",
-          `${relativePath}: 一期禁止 Node builtin ${specifier}`,
-        );
-      }
-      if (!specifier.startsWith(".") && !SDK_IMPORTS.has(specifier)) {
-        throw toolchainError(
-          "zhike_external_dependency_forbidden",
-          `${relativePath}: 一期禁止第三方或内部依赖 ${specifier}`,
-        );
-      }
-      if (specifier.startsWith(".")) {
+      if (!specifier.startsWith(".")) assertAllowedPackageImport(specifier, target, relativePath);
+      if (specifier.startsWith(".") && !options.dependency) {
         const resolvedSourcePath = posix.normalize(
           posix.join(posix.dirname(relativePath), specifier),
         );
@@ -694,6 +688,23 @@ function rejectUnsupportedPaths(files) {
         `${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",