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

package/src/client/points.generated.js

@@ -0,0 +1,19 @@
+// 此文件由 scripts/generate-components.mjs 生成，请修改产品能力声明。
+export const frontendPoints = Object.freeze([
+  {
+    "key": "app.settings",
+    "kind": "view",
+    "legacyType": "settings",
+    "definitionName": "SettingsExtensionDefinition",
+    "maxPerApp": 1
+  },
+  {
+    "key": "app.record-actions",
+    "kind": "action",
+    "legacyType": "record-action",
+    "definitionName": "RecordActionDefinition",
+    "callbackName": "onTrigger",
+    "maxPerApp": 100
+  }
+].map(Object.freeze));
+export const frontendPoint = type => frontendPoints.find(point => point.legacyType === type);

package/src/config.js

@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+
+import { ZhikeCliError } from "./errors.js";
+
+export const CLI_CLIENT_ID = "zhike-cli";
+const metadata = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+export const TOOLING_VERSION = metadata.version;
+
+const CLI_ORIGIN_VARIABLES = Object.freeze([
+  "ZHIKE_DEVELOPER_API_URL",
+  "ZHIKE_DEVELOPER_CONSOLE_URL",
+  "ZHIKE_WORKSPACE_APP_URL",
+]);
+
+export function normalizeOrigin(value, fieldName) {
+  try {
+    const url = new URL(value);
+    if (
+      !["http:", "https:"].includes(url.protocol) ||
+      url.username ||
+      url.password ||
+      url.pathname !== "/" ||
+      url.search ||
+      url.hash
+    ) {
+      throw new Error("invalid origin");
+    }
+    return url.origin;
+  } catch (error) {
+    throw new ZhikeCliError(
+      "zhike_environment_invalid",
+      `${fieldName} 必须是无凭据、无路径的 HTTP(S) origin`,
+      { cause: error },
+    );
+  }
+}
+
+export function loadCliConfig(environment = process.env) {
+  const missing = CLI_ORIGIN_VARIABLES.filter(
+    (name) => typeof environment[name] !== "string" || !environment[name].trim(),
+  );
+  if (missing.length) {
+    throw new ZhikeCliError(
+      "zhike_environment_required",
+      `缺少 CLI 环境变量：${missing.join(", ")}`,
+    );
+  }
+  return {
+    apiBaseUrl: normalizeOrigin(
+      environment.ZHIKE_DEVELOPER_API_URL,
+      "ZHIKE_DEVELOPER_API_URL",
+    ),
+    consoleBaseUrl: normalizeOrigin(
+      environment.ZHIKE_DEVELOPER_CONSOLE_URL,
+      "ZHIKE_DEVELOPER_CONSOLE_URL",
+    ),
+    workspaceBaseUrl: normalizeOrigin(
+      environment.ZHIKE_WORKSPACE_APP_URL,
+      "ZHIKE_WORKSPACE_APP_URL",
+    ),
+  };
+}

package/src/development-workspace.js

@@ -0,0 +1,154 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import { ZhikeCliError } from "./errors.js";
+
+export const DEVELOPMENT_WORKSPACE_PATH = ".zhike/development.json";
+
+export function parseDevelopmentWorkspaceState(value) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).sort().join(",") !== "currentWorkspaceId,schemaVersion" ||
+    value.schemaVersion !== 1 ||
+    !isStableId(value.currentWorkspaceId)
+  ) {
+    throw new ZhikeCliError(
+      "zhike_development_workspace_invalid",
+      `${DEVELOPMENT_WORKSPACE_PATH} 不是受支持的Development Workspace状态`,
+    );
+  }
+  return Object.freeze({ ...value });
+}
+
+export async function readDevelopmentWorkspace(projectDirectory) {
+  let content;
+  try {
+    content = await readFile(resolve(projectDirectory, DEVELOPMENT_WORKSPACE_PATH), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw new ZhikeCliError(
+      "zhike_development_workspace_read_failed",
+      "无法读取当前Development Workspace",
+      { cause: error },
+    );
+  }
+  try {
+    return parseDevelopmentWorkspaceState(JSON.parse(content));
+  } catch (error) {
+    if (error instanceof ZhikeCliError) throw error;
+    throw new ZhikeCliError(
+      "zhike_development_workspace_invalid",
+      `${DEVELOPMENT_WORKSPACE_PATH} 不是受支持的Development Workspace状态`,
+      { cause: error },
+    );
+  }
+}
+
+export async function writeDevelopmentWorkspace(projectDirectory, workspaceId) {
+  const state = parseDevelopmentWorkspaceState({
+    schemaVersion: 1,
+    currentWorkspaceId: workspaceId,
+  });
+  const directory = resolve(projectDirectory, ".zhike");
+  const target = resolve(projectDirectory, DEVELOPMENT_WORKSPACE_PATH);
+  const temporary = `${target}.${randomUUID()}.tmp`;
+  try {
+    await mkdir(directory, { recursive: true });
+    await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { flag: "wx" });
+    await rename(temporary, target);
+  } catch (error) {
+    throw new ZhikeCliError(
+      "zhike_development_workspace_write_failed",
+      "无法保存当前Development Workspace",
+      { cause: error },
+    );
+  }
+  return state;
+}
+
+export async function resolveDevelopmentWorkspace({
+  workspaces,
+  currentWorkspaceId = null,
+  requestedWorkspaceId = null,
+  selectWorkspace = promptForWorkspace,
+}) {
+  const normalized = normalizeWorkspaces(workspaces);
+  if (normalized.length === 0) {
+    throw new ZhikeCliError(
+      "zhike_manageable_workspace_missing",
+      "当前账号没有可用于App开发的Workspace管理权限",
+    );
+  }
+  if (requestedWorkspaceId) {
+    const requested = normalized.find(({ id }) => id === requestedWorkspaceId);
+    if (!requested) throw workspaceNotManageable();
+    return requested;
+  }
+  const current = normalized.find(({ id }) => id === currentWorkspaceId);
+  const selectedId = await selectWorkspace(normalized, current?.id ?? null);
+  const selected = normalized.find(({ id }) => id === selectedId);
+  if (!selected) throw workspaceNotManageable();
+  return selected;
+}
+
+export async function promptForWorkspace(workspaces, defaultWorkspaceId = null) {
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const defaultIndex = workspaces.findIndex(({ id }) => id === defaultWorkspaceId);
+    process.stdout.write("请选择当前Development Workspace：\n");
+    workspaces.forEach((workspace, index) => {
+      process.stdout.write(
+        `  ${index + 1}. ${workspace.name} (${workspace.id})${index === defaultIndex ? " [上次选择，默认]" : ""}\n`,
+      );
+    });
+    const answer = (await prompt.question(defaultIndex >= 0
+      ? `输入序号（回车选择 ${defaultIndex + 1}）：`
+      : "输入序号：")).trim();
+    if (!answer) return workspaces[defaultIndex]?.id ?? "";
+    const index = /^\d+$/.test(answer) ? Number(answer) - 1 : -1;
+    return workspaces[index]?.id ?? "";
+  } finally {
+    prompt.close();
+  }
+}
+
+function normalizeWorkspaces(value) {
+  if (!Array.isArray(value)) throw workspaceResponseInvalid();
+  const ids = new Set();
+  return value.map((workspace) => {
+    if (
+      !workspace ||
+      typeof workspace !== "object" ||
+      !isStableId(workspace.id) ||
+      typeof workspace.name !== "string" ||
+      !workspace.name.trim() ||
+      ids.has(workspace.id)
+    ) {
+      throw workspaceResponseInvalid();
+    }
+    ids.add(workspace.id);
+    return Object.freeze({ id: workspace.id, name: workspace.name.trim() });
+  });
+}
+
+function isStableId(value) {
+  return typeof value === "string" && /^[0-9A-HJKMNP-TV-Z]{26}$/.test(value);
+}
+
+function workspaceNotManageable() {
+  return new ZhikeCliError(
+    "zhike_workspace_not_manageable",
+    "选择的Workspace不存在或当前账号已无管理权限",
+  );
+}
+
+function workspaceResponseInvalid() {
+  return new ZhikeCliError(
+    "zhike_manageable_workspaces_invalid",
+    "Developer Server返回了不受支持的Workspace列表",
+  );
+}

package/src/errors.js

@@ -0,0 +1,20 @@
+export class ZhikeCliError extends Error {
+  constructor(code, message, options = {}) {
+    super(message, options);
+    this.name = "ZhikeCliError";
+    this.code = code;
+    this.exitCode = options.exitCode ?? 1;
+    this.retryable = options.retryable ?? false;
+  }
+}
+
+export function asSafeCliError(error) {
+  if (error instanceof ZhikeCliError) {
+    return error;
+  }
+  return new ZhikeCliError(
+    "zhike_unexpected_error",
+    "操作失败，请检查 Developer Server 状态后重试",
+    { cause: error, retryable: true },
+  );
+}

package/src/forms/components.generated.js

@@ -0,0 +1,4 @@
+// 此文件由 scripts/generate-components.mjs 生成，请修改产品能力声明。
+export const fieldComponents = Object.freeze(["TextInput","Checkbox","Select","Combobox","MemberCombobox","TeamCombobox"]);
+export const boundComponents = Object.freeze(["TextInput","Checkbox","Select","Combobox","MemberCombobox","TeamCombobox","SubmitButton"]);
+export const formComponent = "Form";

package/src/forms/factory.js

@@ -0,0 +1,27 @@
+import { boundComponents, formComponent } from './components.generated.js';
+import { useNormalizedOptions } from './normalize-options.js';
+export function createFormHook({ createElement, useId, useMemo, useRef }) {
+
+return function useForm(options) {
+  const formId = useId();
+  const initial = useRef(options);
+  return useMemo(() => {
+    const { schema, initialValues } = initial.current;
+    const field = type => function Field({ children, ...props }) {
+      if (type === 'Combobox') {
+        const { options, ...rest } = props;
+        const normalized = useNormalizedOptions({ useRef, useMemo }, options);
+        return createElement(type, { ...rest, ...normalized, formId });
+      }
+      return createElement(type, { ...props, formId }, children);
+    };
+    return Object.freeze({
+      Form: function Form({ children, onSubmit }) {
+        return createElement(formComponent, { formId, schema, initialValues, onSubmit }, children);
+      },
+      ...Object.fromEntries(boundComponents.map(type => [type, field(type)])),
+    });
+  }, [formId]);
+}
+
+}

package/src/forms/index.d.ts

@@ -0,0 +1,54 @@
+// 此文件由 scripts/generate-components.mjs 生成，请修改产品能力声明。
+import type { ComponentType, ReactNode } from "react";
+import type { FormSchema, FormValues, FieldName, FormSubmitResult } from "./schema.js";
+import type { Option, OptionsPage, OptionsProvider } from "./options.js";
+export type { Option, OptionsPage, OptionsProvider } from "./options.js";
+export type { FormField, FormSchema, FormValues, FieldName, FormSubmitResult } from "./schema.js";
+export interface FormHandle<S extends FormSchema> {
+  Form: ComponentType<{
+  children?: ReactNode;
+  onSubmit: (values: FormValues<S>) => FormSubmitResult<S> | Promise<FormSubmitResult<S>>;
+  }>;
+  TextInput: ComponentType<{
+  name: FieldName<S, "string">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  }>;
+  Checkbox: ComponentType<{
+  name: FieldName<S, "boolean">;
+  description?: string;
+  disabled?: boolean;
+  }>;
+  Select: ComponentType<{
+  name: FieldName<S, "enum">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  }>;
+  Combobox: ComponentType<{
+  name: FieldName<S, "string">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  options: readonly Option[] | OptionsProvider;
+  }>;
+  MemberCombobox: ComponentType<{
+  name: FieldName<S, "string">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  }>;
+  TeamCombobox: ComponentType<{
+  name: FieldName<S, "string">;
+  description?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  }>;
+  SubmitButton: ComponentType<{
+  children?: string;
+  disabled?: boolean;
+  }>;
+}
+/** schema 和 initialValues 仅在首次挂载使用；重新渲染不会重置输入。 */
+export function useForm<const S extends FormSchema>(options: { schema: S; initialValues: FormValues<S> }): FormHandle<S>;

package/src/forms/index.js

@@ -0,0 +1,3 @@
+import * as React from "react";
+import { createFormHook } from "./factory.js";
+export const useForm = createFormHook(React);

package/src/forms/normalize-options.js

@@ -0,0 +1,19 @@
+import { assertOptions, assertOptionsSearch, assertOptionsPage, assertOptionValue, assertSelectedOption } from './options.js';
+export function useNormalizedOptions({ useRef, useMemo }, options) {
+  const source = useRef({ options: null, search: null, getOption: null, revision: 0 });
+  const search = options?.search, getOption = options?.getOption;
+  if (source.current.options !== options || source.current.search !== search || source.current.getOption !== getOption) {
+    source.current = { options, search, getOption, revision: source.current.revision + 1 };
+  }
+  const revision = source.current.revision;
+  const normalized = useMemo(() => {
+    if (Array.isArray(options)) return { options: assertOptions(options) };
+    if (!options || typeof search !== 'function' || typeof getOption !== 'function') throw new Error('runtime_options_invalid');
+    return {
+      sourceRevision: String(revision),
+      onSearch: input => Promise.resolve(search.call(options, assertOptionsSearch(input))).then(assertOptionsPage),
+      onGetOption: value => Promise.resolve(getOption.call(options, assertOptionValue(value))).then(option => assertSelectedOption(option, value)),
+    };
+  }, [revision]);
+  return normalized;
+}

package/src/forms/options.d.ts

@@ -0,0 +1,25 @@
+/** value 是持久化标识，label 只负责显示。无法回显不能清除原 value。 */
+export interface Option {
+  value: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+  disabledReason?: string;
+}
+export interface OptionsPage {
+  items: Option[];
+  /** null 表示末页；游标只能在当前搜索下使用。 */
+  nextCursor: string | null;
+}
+export interface OptionsProvider {
+  search(input: { query: string; cursor?: string }): Promise<OptionsPage>;
+  /** null 表示成功查询但无法解析；读取失败应拒绝 Promise。 */
+  getOption(value: string): Promise<Option | null>;
+}
+export const OPTIONS_PAGE_LIMIT: number;
+export function assertOption(value: unknown): Option;
+export function assertOptionValue(value: unknown): string;
+export function assertOptions(value: unknown): Option[];
+export function assertOptionsSearch(value: unknown): { query: string; cursor?: string };
+export function assertOptionsPage(value: unknown): OptionsPage;
+export function assertSelectedOption(option: unknown, value: string): Option | null;

package/src/forms/options.js

@@ -0,0 +1,48 @@
+// SDK 回调与 Host 共用有界 DTO 验证；函数留在 Guest，不传递 Provider 对象。
+const fail = () => { throw new Error('runtime_options_invalid'); };
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const only = (value, keys) => { if (!object(value) || Object.keys(value).some(key => !keys.includes(key))) fail(); };
+export const OPTIONS_PAGE_LIMIT = 100;
+export function assertOption(option) {
+  only(option, ['value', 'label', 'description', 'disabled', 'disabledReason']);
+  assertOptionValue(option.value);
+  if (typeof option.label !== 'string' || !option.label || option.label.length > 200) fail();
+  for (const key of ['description', 'disabledReason']) {
+    if (option[key] !== undefined && (typeof option[key] !== 'string' || option[key].length > 4096)) fail();
+  }
+  if (option.disabled !== undefined && typeof option.disabled !== 'boolean') fail();
+  return option;
+}
+export function assertOptionValue(value) {
+  if (typeof value !== 'string' || !value || value.length > 512) fail();
+  return value;
+}
+export function assertOptions(options) {
+  if (!Array.isArray(options) || options.length > OPTIONS_PAGE_LIMIT) fail();
+  const values = new Set();
+  for (const option of options) {
+    assertOption(option);
+    if (values.has(option.value)) fail();
+    values.add(option.value);
+  }
+  return options;
+}
+export function assertOptionsSearch(input) {
+  only(input, ['query', 'cursor']);
+  if (typeof input.query !== 'string' || input.query.length > 512) fail();
+  if (input.cursor !== undefined && (typeof input.cursor !== 'string' || !input.cursor || input.cursor.length > 4096)) fail();
+  return input;
+}
+export function assertOptionsPage(page) {
+  only(page, ['items', 'nextCursor']);
+  assertOptions(page.items);
+  if (page.nextCursor !== null && (typeof page.nextCursor !== 'string' || !page.nextCursor || page.nextCursor.length > 4096)) fail();
+  return page;
+}
+export function assertSelectedOption(option, value) {
+  assertOptionValue(value);
+  if (option === null) return null;
+  assertOption(option);
+  if (option.value !== value) fail();
+  return option;
+}

package/src/forms/schema.d.ts

@@ -0,0 +1,18 @@
+export type FormField =
+  | { type: "string"; label: string; required?: boolean; maxLength?: number }
+  | { type: "boolean"; label: string; required?: boolean }
+  | { type: "enum"; label: string; required?: boolean; options: readonly { value: string; label: string }[] };
+export interface FormSchema { fields: Readonly<Record<string, FormField>>; }
+export type FormValues<S extends FormSchema> = {
+  [K in keyof S["fields"]]: S["fields"][K] extends { type: "boolean" } ? boolean : string;
+};
+export type FieldName<S extends FormSchema, T extends FormField['type']> = {
+  [K in keyof S['fields']]: S['fields'][K]['type'] extends T ? K : never;
+}[keyof S['fields']] & string;
+/** void 兼容既有提交；失败保留输入，字段名必须属于当前表单。 */
+export type FormSubmitResult<S extends FormSchema> = void | { ok: true } | {
+  ok: false;
+  code: string;
+  message: string;
+  fieldErrors?: Partial<Record<Extract<keyof S['fields'], string>, string>>;
+};

package/src/index.d.ts

@@ -0,0 +1,13 @@
+/** App SDK 支持的严格 JSON 值。 */
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/** 当前 App Bundle 代码 Manifest schema。 */
+export const APP_MANIFEST_SCHEMA_VERSION: "zhike.app-manifest.v1";
+/** 当前 Host SDK ABI 版本。 */
+export const SDK_ABI_VERSION: "2";

package/src/index.js

@@ -0,0 +1,2 @@
+export const APP_MANIFEST_SCHEMA_VERSION = "zhike.app-manifest.v1";
+export const SDK_ABI_VERSION = "2";

package/src/project-binding.js

@@ -0,0 +1,84 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { normalizeOrigin } from "./config.js";
+import { ZhikeCliError } from "./errors.js";
+
+export const PROJECT_BINDING_PATH = ".zhike/project.json";
+const BINDING_KEYS = [
+  "appId",
+  "appSlug",
+  "organizationId",
+  "platformEnvironment",
+  "schemaVersion",
+];
+
+export function parseProjectBinding(value, expectedEnvironment = null) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw _bindingError();
+  }
+  const keys = Object.keys(value).sort();
+  if (
+    keys.length !== BINDING_KEYS.length ||
+    keys.some((key, index) => key !== BINDING_KEYS[index])
+  ) {
+    throw _bindingError();
+  }
+  const environment = normalizeOrigin(
+    value.platformEnvironment,
+    "platformEnvironment",
+  );
+  if (
+    value.schemaVersion !== 1 ||
+    !/^[0-9A-HJKMNP-TV-Z]{26}$/.test(value.appId) ||
+    !/^[0-9A-HJKMNP-TV-Z]{26}$/.test(value.organizationId) ||
+    !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value.appSlug) ||
+    environment !== value.platformEnvironment
+  ) {
+    throw _bindingError();
+  }
+  if (
+    expectedEnvironment &&
+    environment !== normalizeOrigin(expectedEnvironment, "Developer API URL")
+  ) {
+    throw new ZhikeCliError(
+      "zhike_project_environment_mismatch",
+      "当前项目绑定的 Developer 环境与 CLI 目标环境不一致",
+    );
+  }
+  return Object.freeze({ ...value });
+}
+
+export async function readProjectBinding(projectDirectory, expectedEnvironment) {
+  let content;
+  try {
+    content = await readFile(resolve(projectDirectory, PROJECT_BINDING_PATH), "utf8");
+  } catch (error) {
+    throw new ZhikeCliError(
+      "zhike_project_binding_missing",
+      `当前目录缺少 ${PROJECT_BINDING_PATH}`,
+      { cause: error },
+    );
+  }
+  try {
+    return parseProjectBinding(JSON.parse(content), expectedEnvironment);
+  } catch (error) {
+    if (error instanceof ZhikeCliError) {
+      throw error;
+    }
+    throw _bindingError(error);
+  }
+}
+
+export function serializeProjectBinding(binding) {
+  const validated = parseProjectBinding(binding);
+  return `${JSON.stringify(validated, null, 2)}\n`;
+}
+
+function _bindingError(cause) {
+  return new ZhikeCliError(
+    "zhike_project_binding_invalid",
+    `${PROJECT_BINDING_PATH} 不是受支持的严格 Project Binding`,
+    { cause },
+  );
+}