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

package/src/cli/browser-auth.js

@@ -0,0 +1,212 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { promisify } from "node:util";
+
+import { CLI_CLIENT_ID } from "../config.js";
+import { ZhikeCliError } from "../errors.js";
+import { DeveloperApiClient } from "./api-client.js";
+
+const execFile = promisify(execFileCallback);
+
+export async function authorizeCli({
+  apiBaseUrl,
+  consoleBaseUrl,
+  credentialStore,
+  fetchImpl = globalThis.fetch,
+  openBrowser = openSystemBrowser,
+  onProgress = () => {},
+  timeoutMs = 120_000,
+}) {
+  const state = randomBytes(32).toString("base64url");
+  const codeVerifier = randomBytes(48).toString("base64url");
+  const codeChallenge = createHash("sha256")
+    .update(codeVerifier, "ascii")
+    .digest("base64url");
+  const callback = await createLoopbackCallback({ state, timeoutMs });
+  const redirectUri = `http://127.0.0.1:${callback.port}/callback`;
+  const authorizationUrl = new URL("/cli/authorize", consoleBaseUrl);
+  authorizationUrl.searchParams.set("client_id", CLI_CLIENT_ID);
+  authorizationUrl.searchParams.set("redirect_uri", redirectUri);
+  authorizationUrl.searchParams.set("code_challenge", codeChallenge);
+  authorizationUrl.searchParams.set("code_challenge_method", "S256");
+  authorizationUrl.searchParams.set("state", state);
+
+  try {
+    callback.waitForCode.catch(() => {});
+    onProgress("正在浏览器中完成 Developer CLI 授权...");
+    await openBrowser(authorizationUrl.toString());
+    const code = await callback.waitForCode;
+    onProgress("已收到浏览器授权，正在完成 Developer CLI 登录...");
+    const api = new DeveloperApiClient({ apiBaseUrl, fetchImpl });
+    const token = await api.exchangeCliAuthorization({
+      code,
+      client_id: CLI_CLIENT_ID,
+      redirect_uri: redirectUri,
+      code_verifier: codeVerifier,
+    });
+    await credentialStore.set(apiBaseUrl, token.refresh_credential);
+    return renewableClient(api, token.access_token, credentialStore);
+  } finally {
+    await callback.close();
+  }
+}
+
+export async function authenticateCli({
+  apiBaseUrl,
+  consoleBaseUrl,
+  credentialStore,
+  fetchImpl = globalThis.fetch,
+  openBrowser = openSystemBrowser,
+  onProgress = () => {},
+  allowBrowserAuthorization = false,
+}) {
+  const api = new DeveloperApiClient({ apiBaseUrl, fetchImpl });
+  const refreshCredential = await credentialStore.get(apiBaseUrl);
+  if (refreshCredential) {
+    onProgress("正在验证已保存的 Developer CLI 登录...");
+    let token;
+    try {
+      token = await api.refreshCliSession(refreshCredential);
+    } catch (error) {
+      if (!(error instanceof ZhikeCliError) || error.retryable) {
+        throw error;
+      }
+      await credentialStore.delete(apiBaseUrl);
+      onProgress("已保存的 Developer CLI 登录已失效。");
+    }
+    if (token) {
+      if (token.refresh_credential !== refreshCredential) {
+        await credentialStore.set(apiBaseUrl, token.refresh_credential);
+      }
+      return renewableClient(api, token.access_token, credentialStore);
+    }
+  }
+  if (!allowBrowserAuthorization) {
+    throw new ZhikeCliError(
+      "zhike_cli_auth_required",
+      "Developer CLI 未登录，请先在本机终端显式运行 zhike login",
+    );
+  }
+  return authorizeCli({
+    apiBaseUrl,
+    consoleBaseUrl,
+    credentialStore,
+    fetchImpl,
+    openBrowser,
+    onProgress,
+  });
+}
+
+export async function openSystemBrowser(url, platform = process.platform) {
+  const command =
+    platform === "darwin"
+      ? ["open", [url]]
+      : platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  try {
+    await execFile(command[0], command[1], {
+      windowsHide: true,
+    });
+  } catch (error) {
+    throw new ZhikeCliError(
+      "zhike_browser_open_failed",
+      `无法自动打开浏览器，请手动访问：${url}`,
+      { cause: error },
+    );
+  }
+}
+
+function renewableClient(api, accessToken, credentialStore) {
+  const client = api.withAccessToken(accessToken);
+  client.refreshAccessToken = async () => {
+    const refreshCredential = await credentialStore.get(api.apiBaseUrl);
+    if (!refreshCredential) {
+      throw new ZhikeCliError("zhike_cli_auth_required", "Developer CLI 登录已失效，请重新登录");
+    }
+    const token = await api.refreshCliSession(refreshCredential);
+    if (token.refresh_credential !== refreshCredential) {
+      await credentialStore.set(api.apiBaseUrl, token.refresh_credential);
+    }
+    return token.access_token;
+  };
+  return client;
+}
+
+async function createLoopbackCallback({ state, timeoutMs }) {
+  let timer;
+  let resolveCode;
+  let rejectCode;
+  const waitForCode = new Promise((resolve, reject) => {
+    resolveCode = resolve;
+    rejectCode = reject;
+  });
+  const server = createServer((request, response) => {
+    const url = new URL(request.url || "/", "http://127.0.0.1");
+    const receivedState = url.searchParams.get("state") || "";
+    const code = url.searchParams.get("code");
+    if (
+      url.pathname !== "/callback" ||
+      !code ||
+      !_safeEqual(receivedState, state)
+    ) {
+      response.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+      response.end("CLI 授权回调无效，可以关闭此页面。");
+      rejectCode(
+        new ZhikeCliError(
+          "zhike_cli_callback_invalid",
+          "CLI 授权回调无效",
+        ),
+      );
+      return;
+    }
+    response.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+    response.end("智客 Developer CLI 已授权，可以关闭此页面。");
+    resolveCode(code);
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    server.close();
+    throw new ZhikeCliError(
+      "zhike_cli_callback_unavailable",
+      "无法启动本机 CLI 授权回调",
+    );
+  }
+  timer = setTimeout(() => {
+    rejectCode(
+      new ZhikeCliError("zhike_cli_authorization_timeout", "CLI 授权已超时"),
+    );
+    server.close();
+    server.closeAllConnections();
+  }, timeoutMs);
+  timer.unref();
+  return {
+    port: address.port,
+    waitForCode,
+    close: async () => {
+      clearTimeout(timer);
+      if (!server.listening) {
+        return;
+      }
+      await new Promise((resolve) => {
+        server.close(resolve);
+        // Chrome 可能预建尚未发送 HTTP 的 TCP 连接；仅 close 会一直等待它。
+        server.closeAllConnections();
+      });
+    },
+  };
+}
+
+function _safeEqual(actual, expected) {
+  const actualBytes = Buffer.from(actual);
+  const expectedBytes = Buffer.from(expected);
+  return (
+    actualBytes.length === expectedBytes.length &&
+    timingSafeEqual(actualBytes, expectedBytes)
+  );
+}

package/src/cli/credential-store.js

@@ -0,0 +1,101 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+
+import { ZhikeCliError } from "../errors.js";
+
+const execFile = promisify(execFileCallback);
+const KEYCHAIN_SERVICE = "com.77hub.zhike.developer-cli";
+
+export class MemoryCredentialStore {
+  constructor() {
+    this.values = new Map();
+  }
+
+  async get(environmentId) {
+    return this.values.get(environmentId) ?? null;
+  }
+
+  async set(environmentId, refreshCredential) {
+    this.values.set(environmentId, refreshCredential);
+  }
+
+  async delete(environmentId) {
+    this.values.delete(environmentId);
+  }
+}
+
+export class MacOSKeychainCredentialStore {
+  constructor({ runner = execFile } = {}) {
+    this.runner = runner;
+  }
+
+  async get(environmentId) {
+    try {
+      const { stdout } = await this.runner("security", [
+        "find-generic-password",
+        "-a",
+        environmentId,
+        "-s",
+        KEYCHAIN_SERVICE,
+        "-w",
+      ]);
+      return stdout.trim() || null;
+    } catch (error) {
+      if (error?.code === 44) {
+        return null;
+      }
+      throw _keychainError(error);
+    }
+  }
+
+  async set(environmentId, refreshCredential) {
+    try {
+      await this.runner("security", [
+        "add-generic-password",
+        "-U",
+        "-a",
+        environmentId,
+        "-s",
+        KEYCHAIN_SERVICE,
+        "-w",
+        refreshCredential,
+      ]);
+    } catch (error) {
+      throw _keychainError(error);
+    }
+  }
+
+  async delete(environmentId) {
+    try {
+      await this.runner("security", [
+        "delete-generic-password",
+        "-a",
+        environmentId,
+        "-s",
+        KEYCHAIN_SERVICE,
+      ]);
+    } catch (error) {
+      if (error?.code !== 44) {
+        throw _keychainError(error);
+      }
+    }
+  }
+}
+
+export function createSystemCredentialStore(platform = process.platform) {
+  if (platform === "darwin") {
+    return new MacOSKeychainCredentialStore();
+  }
+  throw new ZhikeCliError(
+    "zhike_secure_store_unavailable",
+    "当前操作系统尚未配置安全凭据存储适配器",
+  );
+}
+
+function _keychainError(error) {
+  return new ZhikeCliError(
+    "zhike_secure_store_failed",
+    "无法访问操作系统安全凭据存储",
+    { cause: error },
+  );
+}

package/src/cli/development-app.js

@@ -0,0 +1,77 @@
+import { ZhikeCliError } from "../errors.js";
+import {
+  readDevelopmentWorkspace,
+  resolveDevelopmentWorkspace,
+  writeDevelopmentWorkspace,
+} from "../development-workspace.js";
+import { readProjectBinding } from "../project-binding.js";
+import { uploadAppBundle } from "./upload-bundle.js";
+
+export async function runDevelopmentApp({
+  projectDirectory,
+  apiBaseUrl,
+  workspaceBaseUrl,
+  authenticatedApi,
+  requestedWorkspaceId = null,
+  selectWorkspace,
+  upload = uploadAppBundle,
+  expectedScopeRevision,
+  onWorkspaceReady = async () => {},
+}) {
+  const binding = await readProjectBinding(projectDirectory, apiBaseUrl);
+  const workspaces = await authenticatedApi.listManageableWorkspaces();
+  const state = await readDevelopmentWorkspace(projectDirectory);
+  const workspace = await resolveDevelopmentWorkspace({
+    workspaces,
+    currentWorkspaceId: state?.currentWorkspaceId ?? null,
+    requestedWorkspaceId,
+    ...(selectWorkspace ? { selectWorkspace } : {}),
+  });
+
+  await authenticatedApi.ensureWorkspaceVisibility(binding.appId, workspace.id);
+  await writeDevelopmentWorkspace(projectDirectory, workspace.id);
+  await onWorkspaceReady({ binding, workspace });
+
+  const uploaded = await upload({
+    projectDirectory,
+    apiBaseUrl,
+    authenticatedApi,
+    expectedScopeRevision,
+  });
+  const snapshot = {
+    development_revision: uploaded.developmentManifest.revision,
+    manifest_digest: uploaded.developmentManifest.manifest_digest,
+    ...(expectedScopeRevision === undefined ? {} : {
+      expected_scope_configuration_revision: expectedScopeRevision,
+    }),
+  };
+  let application;
+  try {
+    application = await authenticatedApi.applyDevelopmentManifest(
+      binding.appId,
+      workspace.id,
+      snapshot,
+    );
+  } catch (error) {
+    const partial = new ZhikeCliError(
+      "zhike_manifest_updated_workspace_apply_failed",
+      `Development Manifest revision ${snapshot.development_revision} 已更新，但Workspace「${workspace.name}」未应用：${error.message}`,
+      { cause: error, retryable: error?.retryable ?? false },
+    );
+    partial.developmentRevision = snapshot.development_revision;
+    partial.manifestDigest = snapshot.manifest_digest;
+    partial.workspaceId = workspace.id;
+    throw partial;
+  }
+
+  return {
+    binding,
+    workspace,
+    uploaded,
+    application,
+    workspaceAppUrl: new URL(
+      `/web/settings/apps/${encodeURIComponent(binding.appId)}`,
+      workspaceBaseUrl,
+    ).toString(),
+  };
+}

package/src/cli/development-logs.js

@@ -0,0 +1,183 @@
+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 version = entry.app_version_id ? safe(entry.app_version_id).replace(/\n/g, " ").slice(0, 64) : "";
+  const request = entry.invocation_id ? safe(entry.invocation_id).replace(/\n/g, " ").slice(0, 64) : "";
+  const identity = version || request ? `  [${[version, request].filter(Boolean).join(" · ")}]` : "";
+  const prefix = color
+    ? `${colors.dim}${timestamp}${colors.reset}  ${levelColor}${levelLabel}${colors.reset}  ${colors.bold}${label}${colors.reset}${identity}`
+    : `${timestamp}  ${levelLabel}  ${label}${identity}`;
+  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 };
+}