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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@77-zhike/app-sdk",
+  "version": "0.2.0-d7b1.2",
+  "description": "\u667a\u5ba2 Integration App \u4e00\u671f SDK \u4e0e\u672c\u5730 Toolchain",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "zhike": "src/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./client": {
+      "types": "./src/client/index.d.ts",
+      "default": "./src/client/index.js"
+    },
+    "./server": {
+      "types": "./src/server/index.d.ts",
+      "default": "./src/server/index.js"
+    },
+    "./cli": "./src/cli/index.js",
+    "./toolchain": "./src/toolchain/index.js",
+    "./ui": {
+      "types": "./src/ui/index.d.ts",
+      "default": "./src/ui/index.js"
+    },
+    "./forms": {
+      "types": "./src/forms/index.d.ts",
+      "default": "./src/forms/index.js"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "generate:components": "node scripts/generate-components.mjs",
+    "check:components": "node scripts/generate-components.mjs --check",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@types/react": "19.1.0",
+    "esbuild": "0.25.12",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "react": "19.2.5"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}

package/src/bin.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { runCli } from "./cli/index.js";
+
+runCli(process.argv.slice(2)).catch((error) => {
+  if (process.argv.slice(2).includes("--json")) {
+    process.stdout.write(`${JSON.stringify({ schemaVersion: 1, status: "failed", target: null,
+      data: null, effects: { business: "none", authentication: "none" },
+      error: { code: error?.code || "zhike_error" }, nextAction: null })}\n`);
+    process.exitCode = error?.exitCode || 1;
+    return;
+  }
+  process.stderr.write(`[${error?.code || "zhike_error"}] ${error?.message || "操作失败"}\n`);
+  process.exitCode = error?.exitCode || 1;
+});

package/src/cli/api-client.js

@@ -0,0 +1,245 @@
+import { randomUUID } from "node:crypto";
+
+import { ZhikeCliError } from "../errors.js";
+
+export class DeveloperApiClient {
+  constructor({ apiBaseUrl, fetchImpl = globalThis.fetch, accessToken = null }) {
+    this.apiBaseUrl = apiBaseUrl;
+    this.fetchImpl = fetchImpl;
+    this.accessToken = accessToken;
+  }
+
+  withAccessToken(accessToken) {
+    return new DeveloperApiClient({
+      apiBaseUrl: this.apiBaseUrl,
+      fetchImpl: this.fetchImpl,
+      accessToken,
+    });
+  }
+
+  async exchangeCliAuthorization(payload) {
+    return this.request("/api/developer/cli-auth/exchange", {
+      method: "POST",
+      body: payload,
+      authenticated: false,
+    });
+  }
+
+  async refreshCliSession(refreshCredential) {
+    return this.request("/api/developer/cli-auth/refresh", {
+      method: "POST",
+      body: { refresh_credential: refreshCredential },
+      authenticated: false,
+    });
+  }
+
+  async logoutCliSession(refreshCredential) {
+    return this.request("/api/developer/cli-auth/logout", {
+      method: "POST",
+      body: { refresh_credential: refreshCredential },
+      authenticated: false,
+      expectEmpty: true,
+    });
+  }
+
+  async listOrganizations() {
+    return this.request("/api/developer/organizations");
+  }
+
+  async getAppBySlug(organizationId, slug) {
+    const path = `/api/developer/organizations/${encodeURIComponent(
+      organizationId,
+    )}/apps/by-slug/${encodeURIComponent(slug)}`;
+    return this.request(path, { allowNotFound: true });
+  }
+
+  async createApp(organizationId, { name, slug, idempotencyKey }) {
+    return this.request(
+      `/api/developer/organizations/${encodeURIComponent(organizationId)}/apps`,
+      {
+        method: "POST",
+        headers: {
+          "Idempotency-Key": idempotencyKey,
+          "X-Request-ID": randomUUID(),
+        },
+        body: { name, slug },
+      },
+    );
+  }
+
+  async uploadBundle(appId, artifact, idempotencyKey) {
+    return this.request(
+      `/api/developer/apps/${encodeURIComponent(appId)}/bundle-uploads`,
+      {
+        method: "POST",
+        headers: {
+          "Idempotency-Key": idempotencyKey,
+          "X-Zhike-Package-Format": artifact.packageFormat,
+          "X-Zhike-Tooling-Version": artifact.toolingVersion,
+          "X-Zhike-Artifact-Sha256": artifact.sha256,
+          "Content-Type":
+            artifact.contentType || "application/vnd.qiqizhike.mock-build+json",
+        },
+        rawBody: artifact.bytes,
+      },
+    );
+  }
+
+  async getDevelopmentManifest(appId) {
+    return this.request(`/api/developer/apps/${encodeURIComponent(appId)}/development-manifest`);
+  }
+
+  async updateDevelopmentManifest(appId, appBundleId, expectedScopeRevision) {
+    return this.request(
+      `/api/developer/apps/${encodeURIComponent(appId)}/development-manifest`,
+      {
+        method: "PUT",
+        headers: { "X-Request-ID": randomUUID() },
+        body: {
+          app_bundle_id: appBundleId,
+          ...(expectedScopeRevision === undefined ? {} : {
+            expected_scope_configuration_revision: expectedScopeRevision,
+          }),
+        },
+      },
+    );
+  }
+
+  async listManageableWorkspaces() {
+    return this.request("/api/developer/workspaces");
+  }
+
+  async ensureWorkspaceVisibility(appId, workspaceId) {
+    return this.request(
+      `/api/developer/apps/${encodeURIComponent(appId)}`
+        + `/workspace-visibilities/${encodeURIComponent(workspaceId)}`,
+      { method: "PUT" },
+    );
+  }
+
+  async applyDevelopmentManifest(appId, workspaceId, snapshot) {
+    return this.request(
+      `/api/developer/apps/${encodeURIComponent(appId)}`
+        + `/development-workspaces/${encodeURIComponent(workspaceId)}/apply`,
+      { method: "POST", body: snapshot },
+    );
+  }
+
+  async request(
+    path,
+    {
+      method = "GET",
+      headers = {},
+      body,
+      rawBody,
+      authenticated = true,
+      allowNotFound = false,
+      expectEmpty = false,
+      retryAuthentication = true,
+    } = {},
+  ) {
+    const response = await this.openResponse(path, {
+      method, headers, body, rawBody, authenticated, retryAuthentication,
+    });
+    if (allowNotFound && response.status === 404) return null;
+    if (!response.ok) throw await responseError(response);
+    if (expectEmpty || response.status === 204) return null;
+    return response.json();
+  }
+
+  async openLogStream(appId, workspaceId, { cursor, signal } = {}) {
+    const response = await this.openResponse(
+      `/api/developer/apps/${encodeURIComponent(appId)}`
+        + `/development-workspaces/${encodeURIComponent(workspaceId)}/logs/stream`,
+      { headers: { Accept: "text/event-stream", ...(cursor ? { "Last-Event-ID": cursor } : {}) },
+        signal, timeoutMs: null },
+    );
+    if (!response.ok) throw await responseError(response);
+    return response;
+  }
+
+  // JSON 与 SSE 共用认证状态；连接取消和超时仍由每次请求独立管理。
+  async openResponse(path, {
+    method = "GET", headers = {}, body, rawBody, authenticated = true,
+    retryAuthentication = true, signal = this.signal, timeoutMs = 30_000,
+  } = {}) {
+    if (authenticated && !this.accessToken) {
+      throw new ZhikeCliError(
+        "zhike_cli_auth_required",
+        "需要先完成 Developer CLI 授权",
+      );
+    }
+    let response;
+    const usedToken = this.accessToken;
+    const requestSignal = timeoutMs === null ? signal
+      : AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(timeoutMs)]);
+    try {
+      response = await this.fetchImpl(new URL(path, this.apiBaseUrl), {
+        method,
+        headers: {
+          Accept: "application/json",
+          ...(body === undefined || rawBody !== undefined
+            ? {}
+            : { "Content-Type": "application/json" }),
+          ...(authenticated
+            ? { Authorization: `Bearer ${usedToken}` }
+            : {}),
+          ...headers,
+        },
+        body: rawBody ?? (body === undefined ? undefined : JSON.stringify(body)),
+        signal: requestSignal,
+      });
+    } catch (error) {
+      throw new ZhikeCliError(
+        "zhike_developer_server_unavailable",
+        "无法连接 Developer Server",
+        { cause: error, retryable: true },
+      );
+    }
+    if (response.status === 401 && authenticated && retryAuthentication && this.refreshAccessToken) {
+      await response.body?.cancel();
+      // 迟到的旧 Token 401 不再触发第二次刷新。
+      if (this.accessToken === usedToken) {
+        this.refreshing ??= Promise.resolve().then(() => this.refreshAccessToken())
+          .then((token) => { this.accessToken = token; })
+          .finally(() => { this.refreshing = null; });
+        await waitForRefresh(this.refreshing, requestSignal);
+      }
+      requestSignal?.throwIfAborted();
+      return this.openResponse(path, {
+        method, headers, body, rawBody, authenticated, signal: requestSignal,
+        timeoutMs: null, retryAuthentication: false,
+      });
+    }
+    return response;
+  }
+}
+
+function waitForRefresh(refreshing, signal) {
+  if (!signal) return refreshing;
+  return new Promise((resolve, reject) => {
+    const aborted = () => reject(signal.reason);
+    if (signal.aborted) return aborted();
+    signal.addEventListener("abort", aborted, { once: true });
+    refreshing.then(resolve, reject).finally(() => signal.removeEventListener("abort", aborted));
+  });
+}
+
+async function responseError(response) {
+  const payload = await _safeJson(response);
+  const error = new ZhikeCliError(
+    payload?.code || payload?.detail?.code || "zhike_developer_api_failed",
+    payload?.detail?.message || (typeof payload?.detail === "string" ? payload.detail : null) || "Developer API 请求失败",
+    { retryable: response.status >= 500 || response.status === 429 },
+  );
+  error.statusCode = response.status;
+  return error;
+}
+
+async function _safeJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}

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(),
+  };
+}