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

package/src/cli/development-watch.js

@@ -0,0 +1,205 @@
+import { watch } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+
+import { ZhikeCliError } from "../errors.js";
+import { readProjectBinding } from "../project-binding.js";
+import { runDevelopmentApp } from "./development-app.js";
+import { uploadAppBundle } from "./upload-bundle.js";
+import { startDevelopmentLogs } from "./development-logs.js";
+
+/** 一个 dev 进程只拥有一个 Workspace；watch、upload 和远端更新串行处理。 */
+export async function watchDevelopmentApp({
+  projectDirectory, apiBaseUrl, authenticatedApi, onReady = async () => {},
+  onProgress = () => {}, signal, pollIntervalMs = 2_000, debounceMs = 200,
+  upload = uploadAppBundle, ...options
+}) {
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  const watchSignal = controller.signal;
+  let changes = 0;
+  let changedAt = 0;
+  let wake;
+  let timer;
+  let watcherError;
+  let logSubscription;
+  const watchers = [];
+  const previousSignal = authenticatedApi.signal;
+  authenticatedApi.signal = watchSignal;
+  const changed = () => {
+    changes += 1;
+    changedAt = Date.now();
+    wake?.();
+  };
+  const wait = (milliseconds) => new Promise((resolveWait) => {
+    const finish = () => {
+      clearTimeout(timer);
+      watchSignal.removeEventListener("abort", finish);
+      wake = null;
+      resolveWait();
+    };
+    if (watchSignal.aborted) return resolveWait();
+    wake = finish;
+    timer = setTimeout(finish, milliseconds);
+    watchSignal.addEventListener("abort", finish, { once: true });
+  });
+  signal?.addEventListener("abort", stop, { once: true });
+  if (signal?.aborted) stop();
+  if (!signal) {
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+  }
+  try {
+    if (watchSignal.aborted) return null;
+    const binding = await readProjectBinding(projectDirectory, apiBaseUrl);
+    watchers.push(watch(resolve(projectDirectory, "src"), { recursive: true }, changed));
+    watchers.push(watch(projectDirectory, (_event, name) => {
+      if (name && /^(package(?:-lock)?\.json|pnpm-lock\.yaml|tsconfig(?:\.[\w-]+)?\.json)$/.test(String(name))) changed();
+    }));
+    for (const watcher of watchers) watcher.on("error", (error) => {
+      watcherError = error;
+      stop();
+    });
+    const current = await authenticatedApi.getDevelopmentManifest(binding.appId);
+    const scopeRevision = current.scope_configuration_revision;
+    if (!Number.isSafeInteger(scopeRevision) || scopeRevision < 0) {
+      throw new ZhikeCliError("zhike_dev_server_upgrade_required", "Developer Server 尚不支持 dev watch，请更新服务后重试");
+    }
+    let syncedChanges = changes;
+    let sourceDigest = await fingerprintSources(projectDirectory);
+    onProgress("正在构建、上传并同步到开发 Workspace...");
+    let result = await runDevelopmentApp({
+      ...options, projectDirectory, apiBaseUrl, authenticatedApi, upload,
+      expectedScopeRevision: scopeRevision,
+      onWorkspaceReady: async ({ binding: selected, workspace }) => {
+        logSubscription = startDevelopmentLogs({
+          api: authenticatedApi, appId: selected.appId, workspaceId: workspace.id,
+          appLabel: selected.appSlug || selected.appId, signal: watchSignal,
+          onLog: onProgress, onStatus: onProgress,
+        });
+        await logSubscription.ready;
+      },
+    });
+    if (watchSignal.aborted) return result;
+    await onReady(result);
+    onProgress("正在监听代码变化。按 Ctrl+C 结束开发；已安装的 App 会保留。");
+    let lastDigest = result.uploaded.developmentManifest.manifest_digest;
+    let warning = null;
+    let pendingUpload = false;
+    while (!watchSignal.aborted) {
+      const remainingDebounce = changedAt + debounceMs - Date.now();
+      if (remainingDebounce > 0) {
+        await wait(remainingDebounce);
+        continue;
+      }
+      try {
+        const latest = await authenticatedApi.getDevelopmentManifest(binding.appId);
+        if (latest.scope_configuration_revision !== scopeRevision) throw scopeChanged();
+        if (watchSignal.aborted) break;
+        let manifest = latest;
+        if (changes !== syncedChanges) {
+          syncedChanges = changes;
+          const digest = await fingerprintSources(projectDirectory);
+          pendingUpload ||= digest !== sourceDigest;
+          sourceDigest = digest;
+        }
+        const codeChanged = pendingUpload;
+        if (codeChanged) {
+          const currentBinding = await readProjectBinding(projectDirectory, apiBaseUrl);
+          if (currentBinding.appId !== binding.appId) {
+            throw new ZhikeCliError("zhike_dev_binding_changed", "项目绑定已变化，请重新运行 npm run dev");
+          }
+          onProgress("检测到代码变化，正在构建并上传...");
+          const uploaded = await upload({
+            projectDirectory, apiBaseUrl, authenticatedApi, expectedScopeRevision: scopeRevision,
+          });
+          manifest = uploaded.developmentManifest;
+          pendingUpload = false;
+        }
+        if (watchSignal.aborted) break;
+        if (codeChanged || manifest.manifest_digest !== lastDigest || result.application.status === "not_installed") {
+          if (manifest.scope_configuration_revision !== scopeRevision) throw scopeChanged();
+          const application = await authenticatedApi.applyDevelopmentManifest(
+            binding.appId, result.workspace.id, {
+              development_revision: manifest.revision,
+              manifest_digest: manifest.manifest_digest,
+              expected_scope_configuration_revision: scopeRevision,
+            },
+          );
+          if (watchSignal.aborted) break;
+          if (manifest.manifest_digest !== lastDigest || application.status !== result.application.status || codeChanged) {
+            onProgress(application.status === "applied"
+              ? `Revision ${manifest.revision} 已应用到 Workspace「${result.workspace.name}」。`
+              : `Revision ${manifest.revision} 已上传；请在 Workspace「${result.workspace.name}」安装 App。`);
+          }
+          result = { ...result, application, uploaded: { developmentManifest: manifest } };
+          lastDigest = manifest.manifest_digest;
+        }
+        warning = null;
+      } catch (error) {
+        if (watchSignal.aborted) break;
+        if (hasCode(error, "developer_scope_configuration_changed")) throw scopeChanged();
+        if (isAuthorizationError(error) || error.code === "zhike_dev_binding_changed") throw error;
+        // 构建错误等到源码变化再试；网络错误保留待上传内容，下一轮继续。
+        if (!error.retryable) pendingUpload = false;
+        const message = `[${error.code || "zhike_dev_sync_failed"}] ${error.message}`;
+        if (message !== warning) onProgress(`${message}\n本次同步未完成；保留原运行版本，继续等待代码修复或服务恢复。`);
+        warning = message;
+      }
+      if (changes === syncedChanges) await wait(pollIntervalMs);
+    }
+    if (watcherError) throw watcherError;
+    onProgress("已停止监听，未卸载 App。");
+    return result;
+  } catch (error) {
+    if (hasCode(error, "developer_scope_configuration_changed")) throw scopeChanged();
+    if (watchSignal.aborted && !watcherError) return null;
+    throw error;
+  } finally {
+    stop();
+    logSubscription?.stop();
+    await logSubscription?.done;
+    clearTimeout(timer);
+    for (const watcher of watchers) watcher.close();
+    signal?.removeEventListener("abort", stop);
+    if (!signal) {
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+    }
+    authenticatedApi.signal = previousSignal;
+  }
+}
+
+function scopeChanged() {
+  return new ZhikeCliError("developer_scope_configuration_changed", "检测到 App Scope 已更新。请重新运行 npm run dev，使新的权限配置生效。");
+}
+
+function hasCode(error, code) {
+  return error?.code === code || (error?.cause && hasCode(error.cause, code));
+}
+
+function isAuthorizationError(error) {
+  return error?.statusCode === 401 || error?.statusCode === 403
+    || hasCode(error, "zhike_cli_auth_required")
+    || (error?.cause && isAuthorizationError(error.cause));
+}
+
+async function fingerprintSources(root) {
+  const hash = createHash("sha256");
+  async function include(path) {
+    const entries = await readdir(resolve(root, path), { withFileTypes: true });
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const file = `${path}/${entry.name}`;
+      if (entry.isDirectory()) await include(file);
+      else if (entry.isFile()) hash.update(file).update("\0").update(await readFile(resolve(root, file))).update("\0");
+    }
+  }
+  await include("src");
+  for (const file of (await readdir(root)).sort()) {
+    if (/^(package(?:-lock)?\.json|pnpm-lock\.yaml|tsconfig(?:\.[\w-]+)?\.json)$/.test(file)) {
+      hash.update(file).update("\0").update(await readFile(resolve(root, file))).update("\0");
+    }
+  }
+  return hash.digest("hex");
+}

package/src/cli/index.js

@@ -0,0 +1,256 @@
+import { resolve } from "node:path";
+
+import { loadCliConfig } from "../config.js";
+import { asSafeCliError, ZhikeCliError } from "../errors.js";
+import { buildAppBundle } from "../toolchain/index.js";
+import { authenticateCli, openSystemBrowser } from "./browser-auth.js";
+import { createSystemCredentialStore } from "./credential-store.js";
+import {
+  assertEmptyTarget,
+  assertExistingProjectTarget,
+  initializeExistingProject,
+  initializeProject,
+  validateAppSlug,
+} from "./project-init.js";
+import { uploadAppBundle } from "./upload-bundle.js";
+import { watchDevelopmentApp } from "./development-watch.js";
+import { runLocalCommand } from "./local-commands.js";
+import { readProjectBinding } from "../project-binding.js";
+import { parseLogsArguments, queryAppLogs } from "./logs.js";
+
+export async function runCli(
+  args,
+  {
+    environment = process.env,
+    cwd = process.cwd(),
+    output = process.stdout,
+    credentialStore = null,
+    authenticate = authenticateCli,
+    scaffold,
+    fetchImpl = globalThis.fetch,
+    openBrowser,
+    selectWorkspace,
+    isInteractive = Boolean(process.stdin.isTTY),
+    developmentRunner = watchDevelopmentApp,
+  } = {},
+) {
+  const [command, ...rest] = args;
+  const localCommand = !command || ["-h", "--help"].includes(command) ? "help" : command;
+  if (["help", "version", "doctor"].includes(localCommand)) {
+    if (rest.filter((arg) => arg === "--json").length > 1) {
+      throw new ZhikeCliError("zhike_arguments_invalid", "--json 不可重复");
+    }
+    const result = await runLocalCommand(localCommand, rest.filter((arg) => arg !== "--json"), { cwd, environment });
+    output.write(rest.includes("--json") ? `${JSON.stringify(result)}\n`
+      : localCommand === "help" ? Object.values(result.data.commands).map((usage) => `  zhike ${usage}\n`).join("")
+      : `${JSON.stringify(result.data, null, 2)}\n`);
+    return result;
+  }
+  if (command !== "logs" && rest.includes("--json")) {
+    throw new ZhikeCliError("zhike_json_not_supported", "此命令暂不支持 --json，请用 help --json 查询支持范围");
+  }
+  try {
+    if (command === "build") {
+      _rejectArguments(rest);
+      const result = await buildAppBundle({
+        projectDirectory: cwd,
+        writeToDist: true,
+      });
+      output.write(
+        `App Bundle Build 完成：${result.artifacts.length} Artifacts，传输包 ${result.sha256} (${result.size} bytes)\n`,
+      );
+      return result;
+    }
+    if (command === "validate") {
+      _rejectArguments(rest);
+      const result = await buildAppBundle({
+        projectDirectory: cwd,
+      });
+      output.write(
+        `真实 App 源码校验通过：${result.artifacts.length} Artifacts，Bundle ${result.sha256} (${result.size} bytes)；未写入 dist\n`,
+      );
+      return result;
+    }
+
+    const onProgress = (message) => output.write(`${message}\n`);
+    let remoteContext = null;
+    const getRemoteContext = () => {
+      remoteContext ??= {
+        config: loadCliConfig(environment),
+        store: credentialStore || createSystemCredentialStore(),
+      };
+      return remoteContext;
+    };
+    if (command === "logs") {
+      const parsed = parseLogsArguments(rest);
+      const { config, store } = getRemoteContext();
+      const binding = await readProjectBinding(cwd, config.apiBaseUrl);
+      const api = await authenticate({ ...config, credentialStore: store, fetchImpl, openBrowser,
+        onProgress: parsed.json ? () => {} : onProgress });
+      return await queryAppLogs({ api, binding, ...parsed, output });
+    }
+    if (command === "login") {
+      _rejectArguments(rest);
+      const { config, store } = getRemoteContext();
+      await authenticate({
+        ...config,
+        credentialStore: store,
+        fetchImpl,
+        openBrowser,
+        onProgress,
+        allowBrowserAuthorization: true,
+      });
+      output.write("Developer CLI 授权成功。\n");
+      return { command: "login" };
+    }
+    if (command === "init") {
+      const here = rest.includes("--here");
+      const slugArgs = rest.filter((arg) => arg !== "--here");
+      if (slugArgs.length !== 1 || slugArgs[0].startsWith("-") ||
+          rest.length !== (here ? 2 : 1)) {
+        throw new ZhikeCliError(
+          "zhike_init_usage_invalid",
+          "用法：zhike init <app-slug> [--here]",
+        );
+      }
+      const appSlug = validateAppSlug(slugArgs[0]);
+      const targetDirectory = here ? cwd : resolve(cwd, appSlug);
+      if (here) await assertExistingProjectTarget(targetDirectory);
+      else await assertEmptyTarget(targetDirectory);
+      const { config, store } = getRemoteContext();
+      const startedAt = Date.now();
+      const authenticatedApi = await authenticate({
+        ...config,
+        credentialStore: store,
+        fetchImpl,
+        openBrowser,
+        onProgress,
+        allowBrowserAuthorization: true,
+      });
+      output.write(
+        `Developer CLI 登录成功（${_formatElapsed(startedAt)}），正在${here ? "绑定当前项目" : "创建 App 和本地项目"}...\n`,
+      );
+      const result = here
+        ? await initializeExistingProject({ projectDirectory: targetDirectory, appSlug,
+          apiBaseUrl: config.apiBaseUrl, authenticatedApi })
+        : await initializeProject({ targetDirectory, appSlug, apiBaseUrl: config.apiBaseUrl,
+          authenticatedApi, ...(scaffold ? { scaffold } : {}) });
+      output.write(
+        `${result.created ? "已创建" : "已复用"} App ${result.app.slug}，项目位于 ${here ? "当前目录" : `${appSlug}/`}（总耗时 ${_formatElapsed(startedAt)}）\n`,
+      );
+      return result;
+    }
+    if (command === "upload") {
+      _rejectArguments(rest);
+      const { config, store } = getRemoteContext();
+      const authenticatedApi = await authenticate({
+        ...config,
+        credentialStore: store,
+        fetchImpl,
+        openBrowser,
+        onProgress,
+      });
+      const result = await uploadAppBundle({
+        projectDirectory: cwd,
+        apiBaseUrl: config.apiBaseUrl,
+        authenticatedApi,
+      });
+      output.write(
+        `Bundle 已受理并更新当前 Development Manifest：revision ${result.developmentManifest.revision}，${result.upload.id} (${result.artifact.artifacts.length} Artifacts)\n`,
+      );
+      return result;
+    }
+    if (command === "dev") {
+      const requestedWorkspaceId = _parseDevArguments(rest);
+      if (!requestedWorkspaceId && !selectWorkspace && !isInteractive) {
+        throw new ZhikeCliError(
+          "zhike_workspace_selection_required",
+          "非交互环境必须显式指定 Workspace：zhike dev --workspace <workspace-id>",
+        );
+      }
+      const { config, store } = getRemoteContext();
+      const authenticatedApi = await authenticate({
+        ...config,
+        credentialStore: store,
+        fetchImpl,
+        openBrowser,
+        onProgress,
+      });
+      let ready = false;
+      const onReady = async (result) => {
+        ready = true;
+        output.write(_developmentResultMessage(result));
+        try {
+          await (openBrowser || openSystemBrowser)(result.workspaceAppUrl);
+        } catch {
+          output.write(`无法自动打开浏览器，请手动访问：${result.workspaceAppUrl}\n`);
+        }
+      };
+      const result = await developmentRunner({
+        projectDirectory: cwd,
+        apiBaseUrl: config.apiBaseUrl,
+        workspaceBaseUrl: config.workspaceBaseUrl,
+        authenticatedApi,
+        requestedWorkspaceId,
+        selectWorkspace,
+        onProgress,
+        onReady,
+      });
+      if (result && !ready) await onReady(result);
+      return result;
+    }
+    throw new ZhikeCliError(
+      "zhike_command_unknown",
+      `未知命令：${command}`,
+    );
+  } catch (error) {
+    throw asSafeCliError(error);
+  }
+}
+
+function _rejectArguments(args) {
+  if (args.length > 0) {
+    throw new ZhikeCliError("zhike_arguments_invalid", "当前命令不接受额外参数");
+  }
+}
+
+function _parseDevArguments(args) {
+  if (args.length === 0) return null;
+  if (args.length === 2 && args[0] === "--workspace" && args[1]) {
+    return args[1];
+  }
+  throw new ZhikeCliError(
+    "zhike_dev_usage_invalid",
+    "用法：zhike dev [--workspace <workspace-id>]",
+  );
+}
+
+function _developmentResultMessage(result) {
+  const revision = result.uploaded.developmentManifest.revision;
+  const workspace = `Workspace「${result.workspace.name}」`;
+  if (result.application.status === "applied") {
+    return `Development Manifest revision ${revision} 已更新；${workspace}已应用 generation ${result.application.generation}。\n`;
+  }
+  if (result.application.status === "not_installed") {
+    return `Development Manifest revision ${revision} 已更新；${workspace}尚未安装，请在标准Apps页面完成安装。\n`;
+  }
+  throw new ZhikeCliError("zhike_dev_server_upgrade_required", "服务端未完成开发同步，请更新 Developer/Main 服务后重试");
+}
+
+function _formatElapsed(startedAt) {
+  const elapsedMs = Math.max(0, Date.now() - startedAt);
+  return elapsedMs < 1_000 ? "不到 1 秒" : `${(elapsedMs / 1_000).toFixed(1)} 秒`;
+}
+
+export { authenticateCli, authorizeCli } from "./browser-auth.js";
+export {
+  MacOSKeychainCredentialStore,
+  MemoryCredentialStore,
+  createSystemCredentialStore,
+} from "./credential-store.js";
+export {
+  assertEmptyTarget,
+  initializeProject,
+  scaffoldProject,
+} from "./project-init.js";
+export { uploadAppBundle } from "./upload-bundle.js";

package/src/cli/local-commands.js

@@ -0,0 +1,80 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+
+import { loadCliConfig } from "../config.js";
+import { ZhikeCliError } from "../errors.js";
+import { readProjectBinding } from "../project-binding.js";
+
+const metadata = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
+export const commandHelp = {
+  help: "help [command] [--json]",
+  version: "version [--json]",
+  doctor: "doctor [--json]",
+  login: "login",
+  init: "init <app-slug> [--here]",
+  validate: "validate",
+  build: "build",
+  upload: "upload",
+  dev: "dev [--workspace <workspace-id>]",
+  logs: "logs --workspace <id> [--since <time|1h|1d>] [--until <time>] [--level log|warn|error] [--keyword <text>] [--version <id>] [--limit 1..100] [--cursor <cursor>] [--json]",
+};
+
+export function localEnvelope(data, status = "completed") {
+  return { schemaVersion: 1, status, target: null, data,
+    effects: { business: "none", authentication: "none" }, error: null, nextAction: null };
+}
+
+/** 本地诊断不调用认证、网络或项目脚本；依赖仅解析路径，不执行包代码。 */
+export async function runLocalCommand(command, args, { cwd, environment }) {
+  if (command === "help") {
+    if (args.length > 1 || (args.length && !Object.hasOwn(commandHelp, args[0]))) {
+      throw new ZhikeCliError("zhike_help_usage_invalid", "用法：help [command] [--json]");
+    }
+    return localEnvelope({ commands: args.length ? { [args[0]]: commandHelp[args[0]] } : commandHelp,
+      jsonCommands: ["help", "version", "doctor", "logs"] });
+  }
+  if (args.length) throw new ZhikeCliError("zhike_arguments_invalid", "当前命令不接受额外参数");
+  if (command === "version") return localEnvelope({ package: metadata.name, version: metadata.version,
+    node: process.version, requiredNode: metadata.engines.node });
+
+  const checks = [];
+  checks.push({ name: "node", ok: Number(process.versions.node.split(".")[0]) >= 20,
+    required: metadata.engines.node, actual: process.version });
+  let config;
+  try {
+    config = loadCliConfig(environment);
+    checks.push({ name: "environment", ok: true, source: "configuration", ...config });
+  } catch (error) {
+    checks.push({ name: "environment", ok: false, code: error.code });
+  }
+  let binding;
+  try {
+    binding = await readProjectBinding(cwd, config?.apiBaseUrl);
+    checks.push({ name: "binding", ok: Boolean(config), appId: binding.appId });
+  } catch (error) {
+    checks.push({ name: "binding", ok: false, code: error.code });
+  }
+  try {
+    const pkg = JSON.parse(await readFile(resolve(cwd, "package.json"), "utf8"));
+    const require = createRequire(resolve(cwd, "package.json"));
+    const dependencies = { ...pkg.dependencies, ...pkg.devDependencies };
+    const sdkDeclared = Boolean(dependencies["@77-zhike/app-sdk"]);
+    checks.push({ name: "sdkDeclaration", ok: sdkDeclared });
+    for (const name of Object.keys(dependencies)) {
+      try {
+        require.resolve(name);
+        checks.push({ name: "dependency", package: name, ok: true });
+      } catch {
+        checks.push({ name: "dependency", package: name, ok: false, code: "dependency_unresolved" });
+      }
+    }
+  } catch {
+    checks.push({ name: "package", ok: false, code: "package_missing_or_invalid" });
+  }
+  checks.push({ name: "secureStore", ok: process.platform === "darwin", platform: process.platform });
+  const result = localEnvelope({ localReady: checks.every((check) => check.ok),
+    authentication: "not_checked", installation: "not_checked", checks });
+  result.target = config ? { environment: config.apiBaseUrl, appId: binding?.appId ?? null } : null;
+  return result;
+}

package/src/cli/logs.js

@@ -0,0 +1,56 @@
+import { ZhikeCliError } from "../errors.js";
+import { formatAppLog } from "./development-logs.js";
+
+const fields = { "--workspace": "workspace_id", "--since": "from", "--until": "to",
+  "--level": "level", "--keyword": "query", "--version": "app_version_id",
+  "--cursor": "cursor", "--limit": "limit" };
+
+/** 查询一页历史日志；不订阅、不构建，也不改变安装状态。 */
+export function parseLogsArguments(args, now = Date.now()) {
+  const query = {}, seen = new Set();
+  let json = false;
+  const invalid = () => { throw new ZhikeCliError("zhike_logs_usage_invalid", "用法：zhike logs --workspace <id> [--since <带时区时间或 1h/1d>] [--until <带时区时间>] [--level log|warn|error] [--keyword <关键词>] [--version <id>] [--limit 1..100] [--cursor <游标>] [--json]；最多查询最近三天"); };
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    if (seen.has(flag)) invalid();
+    seen.add(flag);
+    if (flag === "--json") { json = true; continue; }
+    if (!Object.hasOwn(fields, flag) || !args[i + 1] || args[i + 1].startsWith("--")) invalid();
+    query[fields[flag]] = args[++i];
+  }
+  if (!query.workspace_id || query.workspace_id.length > 128) invalid();
+  if (query.level && !["log", "warn", "error"].includes(query.level)) invalid();
+  if (query.limit && (!/^\d+$/.test(query.limit) || +query.limit < 1 || +query.limit > 100)) invalid();
+  if ((query.query?.length ?? 0) > 200 || (query.cursor?.length ?? 0) > 180 || (query.app_version_id?.length ?? 0) > 128) invalid();
+  const timestamp = (value, relative) => {
+    const match = relative && /^(\d+)(m|h|d)$/.exec(value);
+    const time = match ? now - +match[1] * { m: 60_000, h: 3_600_000, d: 86_400_000 }[match[2]]
+      : /^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(value) ? Date.parse(value) : NaN;
+    if (!Number.isFinite(time)) invalid();
+    return time;
+  };
+  const end = query.to ? timestamp(query.to, false) : now;
+  const start = query.from ? timestamp(query.from, true) : end - 3_600_000;
+  if (start >= end || start < now - 3 * 86_400_000 || end > now) invalid();
+  query.from = new Date(start).toISOString();
+  query.to = new Date(end).toISOString();
+  return { query, json };
+}
+
+export async function queryAppLogs({ api, binding, query, json, output }) {
+  const page = await api.queryAppLogs(binding.appId, query);
+  if (!page || !Array.isArray(page.items) || !(page.next_cursor === null || typeof page.next_cursor === "string")) {
+    throw new ZhikeCliError("zhike_logs_response_invalid", "日志响应格式错误，请检查服务端版本");
+  }
+  const result = { schemaVersion: 1, status: "completed",
+    target: { environment: binding.platformEnvironment, appId: binding.appId, workspaceId: query.workspace_id },
+    data: { ...page, from: query.from, to: query.to },
+    effects: { business: "none", authentication: "session" }, error: null, nextAction: null };
+  if (json) output.write(`${JSON.stringify(result)}\n`);
+  else {
+    for (const entry of page.items) output.write(`${formatAppLog(binding.appSlug, entry)}\n`);
+    if (!page.items.length) output.write("当前条件下没有日志。\n");
+    if (page.next_cursor) output.write(`还有更早日志：保持筛选条件并使用 --since ${query.from} --until ${query.to} --cursor ${JSON.stringify(page.next_cursor)}\n`);
+  }
+  return result;
+}