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

package/src/cli/development-logs.js

@@ -0,0 +1,180 @@
+import { createHash } from "node:crypto";
+import { stripVTControlCharacters } from "node:util";
+
+const colors = {
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  bold: "\x1b[1m",
+  reset: "\x1b[0m",
+};
+
+function formatTimestamp(value) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return "时间未知";
+  const pad = (part, width = 2) => String(part).padStart(width, "0");
+  const offset = -date.getTimezoneOffset();
+  const sign = offset >= 0 ? "+" : "-";
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
+    + ` ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`
+    + ` ${sign}${pad(Math.floor(Math.abs(offset) / 60))}:${pad(Math.abs(offset) % 60)}`;
+}
+
+/** 日志不可信：过滤控制指令，多行逐行带 App 标识，不影响 CLI 自己的颜色。 */
+export function formatAppLog(app, entry, {
+  color = Boolean(process.stdout.isTTY && !process.env.NO_COLOR),
+} = {}) {
+  const safe = (value) => stripVTControlCharacters(String(value))
+    .replace(/\r\n?/g, "\n").replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, "");
+  const label = safe(app).replace(/\n/g, " ").slice(0, 128);
+  const level = ["log", "warn", "error"].includes(entry.level) ? entry.level : "log";
+  const levelLabel = { log: "INFO ", warn: "WARN ", error: "ERROR" }[level];
+  const levelColor = { log: colors.cyan, warn: colors.yellow, error: colors.red }[level];
+  const timestamp = formatTimestamp(entry.received_at);
+  const prefix = color
+    ? `${colors.dim}${timestamp}${colors.reset}  ${levelColor}${levelLabel}${colors.reset}  ${colors.bold}${label}${colors.reset}`
+    : `${timestamp}  ${levelLabel}  ${label}`;
+  return safe(entry.message).split("\n").map((line) => `${prefix}  ${line}`).join("\n");
+}
+
+/** 增量 UTF-8/SSE；只保留一个有界帧，取消时主动释放 reader。 */
+export async function* parseLogEvents(body, { signal, onActivity = () => {} } = {}) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "", event = "message", id, data = [];
+  let frameSize = 0;
+  const cancel = () => { void reader.cancel().catch(() => {}); };
+  signal?.addEventListener("abort", cancel, { once: true });
+  try {
+    if (signal?.aborted) return;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break; // 不展示未完整接收的尾帧，也不推进其游标。
+      onActivity();
+      buffer += decoder.decode(value, { stream: true });
+      let match;
+      while ((match = /\r\n|\r|\n/.exec(buffer))) {
+        if (match[0] === "\r" && match.index === buffer.length - 1) break;
+        const line = buffer.slice(0, match.index);
+        buffer = buffer.slice(match.index + match[0].length);
+        frameSize += line.length;
+        if (frameSize > 70_000) throw new Error("developer_log_frame_too_large");
+        if (!line) {
+          if (data.length) yield { event, id, data: JSON.parse(data.join("\n")) };
+          event = "message"; id = undefined; data = []; frameSize = 0;
+        } else if (!line.startsWith(":")) {
+          const separator = line.indexOf(":");
+          const field = separator < 0 ? line : line.slice(0, separator);
+          const text = separator < 0 ? "" : line.slice(separator + 1).replace(/^ /, "");
+          if (field === "event") event = text;
+          if (field === "id" && !text.includes("\0")) id = text;
+          if (field === "data") data.push(text);
+        }
+      }
+      if (buffer.length + frameSize > 70_000) throw new Error("developer_log_frame_too_large");
+    }
+  } finally {
+    signal?.removeEventListener("abort", cancel);
+    await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}
+
+/** 一个 dev 的日志订阅；ready 有界等待，重连与 code sync 各自取消。 */
+export function startDevelopmentLogs({ api, appId, workspaceId, appLabel = appId,
+  onLog = () => {}, onStatus = () => {}, signal, readyTimeoutMs = 3_000, reconnectMs = 500 }) {
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  signal?.addEventListener("abort", stop, { once: true });
+  if (signal?.aborted) stop();
+  const stream = createHash("sha256").update(JSON.stringify([workspaceId, appId])).digest("hex");
+  let cursor, position = -1n, settled = false, warning = false, idleTimer, delayTimer;
+  let resolveReady;
+  const ready = new Promise((resolve) => { resolveReady = resolve; });
+  const settle = () => { settled = true; clearTimeout(readyTimer); resolveReady(); };
+  const unavailable = () => {
+    if (!warning) onStatus(cursor
+      ? "App 日志连接中断，恢复后从已显示位置补读；代码同步继续。"
+      : "App 日志尚未就绪，代码同步继续；首次连接前的日志可能存在缺口。");
+    warning = true;
+    settle();
+  };
+  const readyTimer = setTimeout(unavailable, readyTimeoutMs);
+  const parseCursor = (value) => {
+    const match = typeof value === "string" && /^1\.([a-f0-9]{64})\.(0|[1-9][0-9]{0,18})\.([0-9]{1,12})$/.exec(value);
+    if (!match || match[1] !== stream || BigInt(match[2]) > 2n ** 63n - 1n) throw new Error("developer_log_cursor_invalid");
+    return BigInt(match[2]);
+  };
+  const done = (async () => {
+    let attempt = 0;
+    try {
+      while (!controller.signal.aborted) {
+        const connection = new AbortController();
+        const connectionSignal = AbortSignal.any([controller.signal, connection.signal]);
+        const activity = () => {
+          clearTimeout(idleTimer);
+          idleTimer = setTimeout(() => connection.abort(), 45_000);
+        };
+        idleTimer = setTimeout(() => connection.abort(), 10_000);
+        try {
+          const response = await api.openLogStream(appId, workspaceId, { cursor, signal: connectionSignal });
+          if (!response.headers.get("content-type")?.startsWith("text/event-stream") || !response.body) {
+            await response.body?.cancel();
+            throw new Error("developer_log_stream_invalid");
+          }
+          activity();
+          for await (const item of parseLogEvents(response.body, { signal: connectionSignal, onActivity: activity })) {
+            if (controller.signal.aborted) break;
+            if (item.event === "gap") {
+              onStatus("App 日志游标超过七天查询窗口，存在缺口；正在补读仍可查询的日志。");
+              cursor = undefined; position = -1n;
+            } else if (item.event === "ready") {
+              const next = parseCursor(item.id);
+              if (next < position) throw new Error("developer_log_cursor_regressed");
+              position = next; cursor = item.id;
+              if (!settled || warning) onStatus("App 实时日志已连接。");
+              settle(); warning = false; attempt = 0;
+            } else if (item.event === "log") {
+              const next = parseCursor(item.id);
+              if (next <= position) continue;
+              if (typeof item.data?.message !== "string" || item.data.message.length > 32_768
+                  || String(item.data.position) !== String(next)) throw new Error("developer_log_entry_invalid");
+              await onLog(formatAppLog(appLabel, item.data));
+              position = next; cursor = item.id; // 完整解析、展示成功后才推进。
+            } else if (item.event === "error") {
+              const error = new Error("developer_log_stream_closed");
+              error.statusCode = item.data?.status;
+              throw error;
+            }
+          }
+          if (!controller.signal.aborted) unavailable();
+        } catch (error) {
+          if (controller.signal.aborted) break;
+          unavailable();
+          if (error.statusCode === 403 || error.statusCode === 404) {
+            onStatus("当前已无权读取此 App/Workspace 日志，停止日志订阅。");
+            break;
+          }
+          if (error.statusCode === 400) {
+            onStatus("App 日志游标已失效，重新连接时可能存在日志缺口。");
+            cursor = undefined; position = -1n;
+          }
+        } finally {
+          clearTimeout(idleTimer);
+          connection.abort();
+        }
+        if (controller.signal.aborted) break;
+        await new Promise((resolve) => {
+          const finish = () => { clearTimeout(delayTimer); controller.signal.removeEventListener("abort", finish); resolve(); };
+          delayTimer = setTimeout(finish, Math.min(reconnectMs * 2 ** Math.min(attempt++, 5), 10_000) * (0.8 + Math.random() * 0.4));
+          controller.signal.addEventListener("abort", finish, { once: true });
+        });
+      }
+    } finally {
+      settle(); clearTimeout(idleTimer); clearTimeout(delayTimer);
+      signal?.removeEventListener("abort", stop);
+    }
+  })();
+  return { ready, done, stop };
+}

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,253 @@
+import { resolve } from "node:path";
+
+import { loadCliConfig } from "../config.js";
+import { asSafeCliError, ZhikeCliError } from "../errors.js";
+import { buildAppBundle, buildMockArtifact } from "../toolchain/index.js";
+import { authenticateCli, openSystemBrowser } from "./browser-auth.js";
+import { createSystemCredentialStore } from "./credential-store.js";
+import {
+  assertEmptyTarget,
+  initializeProject,
+  validateAppSlug,
+} from "./project-init.js";
+import { validateBundleUpload } from "./validate-bundle.js";
+import { uploadAppBundle } from "./upload-bundle.js";
+import { watchDevelopmentApp } from "./development-watch.js";
+import { runLocalCommand } from "./local-commands.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 (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;
+    }
+
+    const onProgress = (message) => output.write(`${message}\n`);
+    let remoteContext = null;
+    const getRemoteContext = () => {
+      remoteContext ??= {
+        config: loadCliConfig(environment),
+        store: credentialStore || createSystemCredentialStore(),
+      };
+      return remoteContext;
+    };
+    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") {
+      if (rest.length !== 1 || rest[0].startsWith("-")) {
+        throw new ZhikeCliError(
+          "zhike_init_usage_invalid",
+          "用法：zhike init <app-slug>",
+        );
+      }
+      const appSlug = validateAppSlug(rest[0]);
+      const targetDirectory = resolve(cwd, appSlug);
+      await assertEmptyTarget(targetDirectory);
+      const { config, store } = getRemoteContext();
+      const startedAt = Date.now();
+      const authenticatedApi = await authenticate({
+        ...config,
+        credentialStore: store,
+        fetchImpl,
+        openBrowser,
+        onProgress,
+      });
+      output.write(
+        `Developer CLI 登录成功（${_formatElapsed(startedAt)}），正在创建 App 和本地项目...\n`,
+      );
+      const result = await initializeProject({
+        targetDirectory,
+        appSlug,
+        apiBaseUrl: config.apiBaseUrl,
+        authenticatedApi,
+        ...(scaffold ? { scaffold } : {}),
+      });
+      output.write(
+        `${result.created ? "已创建" : "已复用"} App ${result.app.slug}，项目位于 ${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;
+    }
+    if (command === "experimental" && rest[0] === "validate-bundle") {
+      _rejectArguments(rest.slice(1));
+      const { config, store } = getRemoteContext();
+      const authenticatedApi = await authenticate({
+        ...config,
+        credentialStore: store,
+        fetchImpl,
+        openBrowser,
+        onProgress,
+      });
+      const result = await validateBundleUpload({
+        projectDirectory: cwd,
+        apiBaseUrl: config.apiBaseUrl,
+        authenticatedApi,
+      });
+      output.write(
+        `${result.upload.status === "accepted" ? "Bundle 已受理" : "Bundle 校验失败"}：${result.upload.id}\n`,
+      );
+      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 { validateBundleUpload } from "./validate-bundle.js";
+export { uploadAppBundle } from "./upload-bundle.js";