@heybox/hb-sdk 0.1.3 → 0.2.0-alpha.1

package/skill/references/cli.md

@@ -0,0 +1,360 @@
+# CLI reference
+
+> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+
+## Sources
+
+- packages/hb-sdk/package.json
+- packages/hb-sdk/src/cli/index.ts
+- packages/hb-sdk/src/cli/commands/create.ts
+- packages/hb-sdk/src/cli/commands/dev.ts
+- packages/hb-sdk/src/cli/commands/login.ts
+- packages/hb-sdk/src/cli/templates/vue3-vite-ts/README.md.ejs
+- apps/h5/docs/hb_sdk/src/guide/cli.md
+- packages/hb-sdk/README.md
+
+## Contents
+
+- [When to use the CLI](#when-to-use-the-cli)
+- [Command surface](#command-surface)
+- [Create a mini-program template](#create-a-mini-program-template)
+- [Local dev and mock runtime](#local-dev-and-mock-runtime)
+- [CLI login cache](#cli-login-cache)
+- [Agent Skill doctor](#agent-skill-doctor)
+- [Update reminders](#update-reminders)
+- [Repository validation commands](#repository-validation-commands)
+- [Generated template README](#generated-template-readme)
+## When to use the CLI
+
+Use the bundled `hb-sdk` CLI when the task is about creating an external mini-program project, starting local Vite development, debugging SDK calls in a browser mock runtime host, or managing the CLI's own Heybox auth cache.
+
+Do not use the CLI to replace iframe SDK calls. `hb-sdk login` is for CLI commands only and does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-host user state.
+
+The CLI, templates, and mock host are owned by `@heybox/hb-sdk`. Do not create a second mock runtime package or move CLI guidance outside this package unless the package boundary changes.
+
+## Command surface
+
+```ts
+import { Command, CommanderError, InvalidArgumentError } from 'commander';
+import { runCreateCommand as defaultRunCreateCommand } from './commands/create';
+import { runDevCommand as defaultRunDevCommand } from './commands/dev';
+import { runDoctorCommand as defaultRunDoctorCommand } from './commands/doctor';
+import {
+  clearLoginStatus as defaultClearLoginStatus,
+  loginToHeybox as defaultLoginToHeybox,
+  printLoginStatus as defaultPrintLoginStatus,
+} from './commands/login';
+import { printUpdateReminder as defaultPrintUpdateReminder } from './update-check';
+import { printError as defaultPrintError } from './utils/errors';
+import { getCliVersion } from './version';
+
+export interface CliCommandHandlers {
+  clearLoginStatus: typeof defaultClearLoginStatus;
+  loginToHeybox: typeof defaultLoginToHeybox;
+  printLoginStatus: typeof defaultPrintLoginStatus;
+  printUpdateReminder: typeof defaultPrintUpdateReminder;
+  runCreateCommand: typeof defaultRunCreateCommand;
+  runDevCommand: typeof defaultRunDevCommand;
+  runDoctorCommand: typeof defaultRunDoctorCommand;
+}
+
+export interface CliRuntimeOptions extends Partial<CliCommandHandlers> {
+  argv?: string[];
+  printError?: typeof defaultPrintError;
+  process?: Pick<NodeJS.Process, 'exit'>;
+}
+
+export async function runCli(options: CliRuntimeOptions = {}) {
+  const processLike = options.process ?? process;
+
+  try {
+    await createCliProgram(options).parseAsync(options.argv ?? process.argv);
+  } catch (error) {
+    if (error instanceof CommanderError && error.exitCode === 0) {
+      processLike.exit(0);
+      return;
+    }
+
+    if (!(error instanceof CommanderError)) {
+      (options.printError ?? defaultPrintError)(error);
+    }
+
+    processLike.exit(error instanceof CommanderError ? error.exitCode : 1);
+  }
+}
+
+export function createCliProgram(overrides: Partial<CliCommandHandlers> = {}) {
+  const handlers: CliCommandHandlers = {
+    clearLoginStatus: defaultClearLoginStatus,
+    loginToHeybox: defaultLoginToHeybox,
+    printLoginStatus: defaultPrintLoginStatus,
+    printUpdateReminder: defaultPrintUpdateReminder,
+    runCreateCommand: defaultRunCreateCommand,
+    runDevCommand: defaultRunDevCommand,
+    runDoctorCommand: defaultRunDoctorCommand,
+    ...overrides,
+  };
+  const program = new Command();
+
+  program
+    .name('hb-sdk')
+    .description('hb-sdk developer tools')
+    .version(getCliVersion())
+    .showHelpAfterError()
+    .exitOverride();
+
+  program
+    .command('create')
+    .description('创建外部小程序项目开发模板')
+    .argument('<project-name>', '项目目录名，例如 my-miniapp')
+    .action(
+      withUpdateReminder(async (projectName) => {
+        await handlers.runCreateCommand(projectName);
+      }, handlers.printUpdateReminder),
+    );
+
+  program
+    .command('dev')
+    .description('启动当前小程序项目的 Vite dev server 和浏览器 mock runtime host')
+    .option('--port <port>', 'App dev server 端口', parsePositivePort)
+    .option('--mock-port <port>', 'Mock host 端口', parsePositivePort)
+    .option('--host <host>', '传给 Vite 和 mock host 的 host')
+    .option('--no-open', '不自动打开浏览器调试页')
+    .action(
+      withUpdateReminder(async (options) => {
+        await handlers.runDevCommand(options);
+      }, handlers.printUpdateReminder),
+    );
+
+  program
+    .command('doctor')
+    .description('诊断 hb-sdk 本地环境和 Agent Skill 版本')
+    .action(async () => {
+      await handlers.runDoctorCommand();
+    });
+
+  const login = program
+    .command('login')
+    .description('登录 Heybox 并缓存 CLI 登录态')
+    .action(
+      withUpdateReminder(async () => {
+        await handlers.loginToHeybox();
+      }, handlers.printUpdateReminder),
+    );
+
+  login
+    .command('status')
+    .description('查看脱敏后的 Heybox 登录态')
+    .action(
+      withUpdateReminder(async () => {
+        await handlers.printLoginStatus();
+      }, handlers.printUpdateReminder),
+    );
+
+  login
+    .command('clear')
+    .description('清理 hb-sdk 命名空间中的 Heybox 登录态')
+    .action(
+      withUpdateReminder(async () => {
+        await handlers.clearLoginStatus();
+      }, handlers.printUpdateReminder),
+    );
+
+  return program;
+}
+
+function withUpdateReminder<Args extends unknown[]>(
+  action: (...args: Args) => Promise<void>,
+  printUpdateReminder: typeof defaultPrintUpdateReminder,
+) {
+  return async (...args: Args) => {
+    await action(...args);
+    await printUpdateReminder();
+  };
+}
+
+function parsePositivePort(value: string) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new InvalidArgumentError('必须是正整数端口号');
+  }
+
+  return parsed;
+}
+```
+
+## Create a mini-program template
+
+## 创建外部小程序模板
+
+```bash
+hb-sdk create my-miniapp
+cd my-miniapp
+npm install
+npm run dev
+```
+
+`hb-sdk create <project-name>` 会生成 Vue 3、Vite、TypeScript 和 npm 模板。`project-name` 同时作为目录名和 `package.json` 的 `name`，必须是合法的非 scoped npm 包名。目标目录不存在时会创建；目标目录已存在但非空时会拒绝覆盖。
+
+CLI 只生成文件，不会自动安装依赖、初始化 git 或打开编辑器。生成模板后优先运行 `npm run dev`，它会启动 Vite 服务和内置 mock runtime host。
+
+Agent rules:
+
+- Prefer `hb-sdk create <project-name>` for a new standalone external mini-program template.
+- After creation, the expected next steps are `npm install` and `npm run dev`.
+- Do not claim the CLI installs dependencies, initializes git, opens an editor, or overwrites non-empty directories.
+- Treat `project-name` as an unscoped npm package name and project directory.
+
+## Local dev and mock runtime
+
+## 本地开发模式
+
+已有小程序项目中可以直接运行：
+
+```bash
+hb-sdk dev
+```
+
+`hb-sdk dev` 会从当前目录向上查找最近的 `package.json` 作为项目根目录，加载该项目安装的 `vite`，并优先使用项目内的 Vite 配置文件。命令会同时启动内置 mock runtime host 并默认打开调试页；如果需要真实黑盒小程序容器加载同一页面，点击调试页里的「在 Mac 版 APP 中启动」按钮。项目没有安装 Vite 时，命令会提示安装依赖或把 Vite 放到 `devDependencies`。
+
+常用参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--port <port>` | 指定小程序 Vite dev server 端口，默认从 `5173` 开始。 |
+| `--mock-port <port>` | 指定 mock host 端口，默认从 `5174` 开始。 |
+| `--host <host>` | 同时传给 Vite 和 mock host 的 host。 |
+| `--no-open` | 不自动打开浏览器调试页。 |
+
+## Mock runtime 边界
+
+`hb-sdk dev` 会把实际小程序页面地址编码到 mock host 的 `mini_url` query 中，由 mock host iframe 加载页面并补齐小程序 bridge 环境。mock host 内置登录/登出、`show`、`hide`、在 Mac 版 APP 中启动等调试按钮，并通过同一份 devtools-only runtime adapter 处理 SDK 能力调用。
+
+不要为了本地调试再创建独立 mock runtime 包。CLI、模板和 mock host 都归属 `@heybox/hb-sdk`。
+
+本地 mock runtime 下的 `network.request()` 会通过 `hb-sdk` 本地 mock network proxy 转发真实 HTTP(S) 请求，用于避免浏览器 CORS 影响本地调试。proxy 不会把黑盒客户端私有协议字段暴露给 iframe 业务代码。
+
+Use `hb-sdk dev` for local browser SDK debugging. Use the Mock runtime host's "在 Mac 版 APP 中启动" button when the page needs to be loaded by the real Heybox mini-program container.
+
+## CLI login cache
+
+## CLI 登录态
+
+```bash
+hb-sdk login
+hb-sdk login status
+hb-sdk login clear
+```
+
+- `hb-sdk login` 会打开 `login.xiaoheihe.cn`，通过本地临时回调服务接收登录结果。
+- `hb-sdk login status` 只展示脱敏状态、`heyboxId`、登录时间和 cache 路径，不输出 `pkey`、cookie 或完整请求头。
+- `hb-sdk login clear` 只清理 `hb-sdk` 自己命名空间中的 Heybox 登录态。
+
+这份 CLI 登录态不会注入 iframe SDK，也不会改变 `hb-sdk dev` 的 mock 用户、`auth.login()`、`user.getInfo()` 或 `network.request()` 行为。
+
+Agent rules:
+
+- Keep CLI auth cache separate from iframe SDK login state.
+- It is correct to say status output is redacted.
+- Do not expose or template pkey, cookie, token, or private credential values.
+- Use `hb-sdk login clear` only to clear the `hb-sdk` CLI namespace.
+
+## Agent Skill doctor
+
+## Agent Skill doctor
+
+```bash
+hb-sdk doctor
+```
+
+`hb-sdk doctor` 用来诊断本机 `hb-sdk` Agent Skill 是否匹配当前 SDK。它会对比当前 `@heybox/hb-sdk` 版本、远端 latest skill 元数据，以及本机 `$CODEX_HOME/skills/hb-sdk/skill.json`；没有 `CODEX_HOME` 时读取 `~/.codex/skills/hb-sdk/skill.json`。
+
+`doctor` 只诊断，不修改本地文件。需要安装或刷新 skill 时，按输出提示手动执行 `npx skills add`。
+
+| 状态 | 含义 |
+| --- | --- |
+| `OK` | SDK、远端 latest skill、本机 skill 全部匹配。 |
+| `SKILL_MISSING` | 本机没有安装 `hb-sdk` skill。 |
+| `SKILL_OUTDATED` | 本机 `skillVersion` 与远端 latest 不一致。 |
+| `SDK_MISMATCH` | 当前 SDK 版本与远端 latest skill 声明的 SDK 版本不一致。 |
+| `REMOTE_UNAVAILABLE` | 无法读取公开 manifest，诊断失败且不会修改本地文件。 |
+
+手动安装或刷新 skill：
+
+```bash
+npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk
+```
+
+如果状态是 `SDK_MISMATCH`，先升级 `@heybox/hb-sdk@latest`，再重新运行 `hb-sdk doctor` 并按提示安装 latest skill。当前只维护 latest skill，不维护历史 SDK 的 skill 快照。
+
+Agent rules:
+
+- Use `hb-sdk doctor` for read-only diagnosis of local SDK, remote latest skill metadata, and local skill metadata.
+- Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
+- If doctor reports `SDK_MISMATCH`, tell the user to upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
+- The supported local skill path is `$CODEX_HOME/skills/hb-sdk/skill.json`, falling back to `~/.codex/skills/hb-sdk/skill.json`.
+
+## Update reminders
+
+## 版本提醒
+
+`hb-sdk` CLI 会在命令成功执行后检查 npm registry 上 `@heybox/hb-sdk` 的 `latest` 版本。检查结果会缓存 24 小时；检查失败会静默跳过；`CI=true` 时会跳过检查，避免污染 CI 日志。本地可通过 `HB_SDK_NO_UPDATE_CHECK=1` 禁用检查。
+
+## Repository validation commands
+
+## 本仓库开发
+
+```bash
+pnpm --filter @heybox/hb-sdk run test:unit
+pnpm --filter @heybox/hb-sdk run build:package
+pnpm --filter @heybox/hb-sdk run check:boundary
+```
+
+`check:boundary` 用于保护 SDK、CLI、mock host 与 runtime 之间的依赖边界。调整 CLI、mock 或协议导出时应一起运行。
+
+## Generated template README
+
+````md
+# <%= projectName %>
+
+这是通过 `hb-sdk create` 生成的黑盒外部小程序开发模板。项目使用 Vue 3、Vite、TypeScript 和 `@heybox/hb-sdk`。
+
+## 使用命令
+
+```bash
+npm install
+npm run dev
+npm run typecheck
+npm run test:unit
+npm run build
+```
+
+## 开发模式
+
+- `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面。
+- `npm run build`：先执行 TypeScript 检查，再构建生产产物。
+
+## 更多能力
+
+模板页面只保留最小接入示例。其他常用能力可以直接从 `@heybox/hb-sdk` 调用：
+
+```ts
+import hbSDK from '@heybox/hb-sdk';
+
+await hbSDK.share.showShareMenu({
+  title: '<%= projectName %>',
+  desc: '分享描述',
+  url: window.location.href,
+});
+
+await hbSDK.storage.setStorage({
+  key: 'settings',
+  data: { theme: 'dark' },
+});
+
+const response = await hbSDK.network.request({
+  method: 'GET',
+  url: 'https://jsonplaceholder.typicode.com/todos/1',
+});
+```
+````

package/skill/references/examples.md

@@ -0,0 +1,107 @@
+# Smoke examples and anti-examples
+
+> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+
+## Sources
+
+- packages/hb-sdk/README.md
+- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/
+## Positive examples
+
+### Minimal user info
+
+```ts
+import { ready, user } from '@heybox/hb-sdk';
+
+await ready();
+
+const result = await user.getInfo();
+if (result.isLogin && result.userInfo) {
+  console.log(result.userInfo.nickname);
+}
+```
+
+### Login gate
+
+```ts
+import { auth, ready, user, HbMiniProgramSDKError } from '@heybox/hb-sdk';
+
+export async function ensureLogin() {
+  await ready();
+
+  const current = await user.getInfo();
+  if (current.isLogin && current.userInfo) return current.userInfo;
+
+  try {
+    const loginResult = await auth.login();
+    return loginResult.userInfo;
+  } catch (error) {
+    if (error instanceof HbMiniProgramSDKError) {
+      console.warn(error.code, error.message);
+    }
+    return null;
+  }
+}
+```
+
+### Network request
+
+```ts
+import { ready, network, HbMiniProgramNetworkError } from '@heybox/hb-sdk';
+
+try {
+  await ready();
+
+  const response = await network.request<{ ok: boolean }>({
+    url: 'https://api.example.com/demo',
+    method: 'GET',
+    validateStatus: status => status >= 200 && status < 400,
+  });
+  console.log(response.data.ok);
+} catch (error) {
+  if (error instanceof HbMiniProgramNetworkError) {
+    console.warn(error.status, error.response?.data);
+  }
+}
+```
+
+### Host/runtime protocol import
+
+```ts
+import { NETWORK_REQUEST_METHOD, type NetworkRequestPayload } from '@heybox/hb-sdk/protocol';
+
+// Host/runtime integration only. Do not use this in iframe business code.
+export function canHandleNetwork(method: string): method is typeof NETWORK_REQUEST_METHOD {
+  return method === NETWORK_REQUEST_METHOD;
+}
+```
+
+### CLI local mock development
+
+```bash
+hb-sdk create my-miniapp
+cd my-miniapp
+npm install
+npm run dev
+
+# In an existing project:
+hb-sdk dev
+```
+
+### CLI login cache
+
+```bash
+hb-sdk login
+hb-sdk login status
+hb-sdk login clear
+```
+
+## Negative examples
+
+- Do not import from internal hb-sdk implementation paths.
+- Do not read cookies, tokens, phone numbers, or private credentials.
+- Do not create raw `postMessage` bridge envelopes in business pages.
+- Do not call unsupported storage delete/clear/info operations.
+- Do not pass raw internal share/network protocol fields from mini-program code.
+- Do not treat `hb-sdk login` as iframe SDK authentication state.
+- Do not create a second mock runtime package when `hb-sdk dev` is the supported local mock workflow.

package/skill/references/llms-index.md

@@ -0,0 +1,44 @@
+# LLM documentation index
+
+> Generated by `node packages/hb-sdk/skill/scripts/sync-references.mjs` from the public hb-sdk source/docs. Do not edit by hand; update sources or this generator instead.
+
+## Sources
+
+- apps/h5/docs/hb_sdk/src/.vuepress/public/llms.txt
+- apps/h5/docs/hb_sdk/src/.vuepress/public/llms/
+## Local generated docs entrypoint
+
+The docs site maintains `llms.txt` and markdown mirrors under `apps/h5/docs/hb_sdk/src/.vuepress/public/llms/`. Read `llms.txt` first for navigation, then the specific guide/reference/recipe markdown needed for the task.
+
+```md
+# @heybox/hb-sdk
+> LLM-friendly index for the `@heybox/hb-sdk` documentation site. API Reference is auto-generated from public exports and source comments; Guide and Recipes are hand-maintained.
+This site documents the iframe-side SDK for external mini programs. For AI retrieval, fetch this index first, then follow the linked markdown mirrors under `./llms/`.
+## Docs
+- [Documentation home](./llms/README.md): 第一次接入时，按下面顺序读：
+- [Guide index](./llms/guide/README.md): Guide 面向第一次接入 `@heybox/hb-sdk` 的开发者，目标是先跑通，再理解边界。
+- [Reference index](./llms/reference/README.md): Reference 由 `packages/hb-sdk` 的公开导出与源码注释自动生成，不重复 Guide 的接入流程。
+- [Recipes index](./llms/recipes/README.md): Recipes 放可以直接复制到业务里的场景写法。它比 Guide 更具体，比 Reference 更偏组合使用。
+- [LLM usage guide](./llms/guide/llms.md): 文档站会自动维护一份标准的 `llms.txt` 索引，以及一组给 AI 直接读取的 Markdown 镜像页，方便模型按文档树逐步抓取内容。
+## API Reference
+- [Root API](./llms/reference/root/README.md): 该页面收录从 `src/index.ts` 公开导出的 API。
+- [Protocol API](./llms/reference/protocol/README.md): 该页面收录从 `src/protocol.ts` 公开导出的 API。
+- [Root functions](./llms/reference/root/functions/README.md)
+- [Root interfaces](./llms/reference/root/interfaces/README.md): 所有请求失败都会被规范化成该结构，SDK 侧再包装为 `HbMiniProgramSDKError`。 |
+- [Protocol interfaces](./llms/reference/protocol/interfaces/README.md): 所有请求失败都会被规范化成该结构，SDK 侧再包装为 `HbMiniProgramSDKError`。 |
+- [Root types](./llms/reference/root/types/README.md): `user.getInfo` 不需要入参。
+- [Protocol types](./llms/reference/protocol/types/README.md): `user.getInfo` 不需要入参。
+## Guides
+- [Agent Skill 安装](./llms/guide/agent-skill.md): `hb-sdk` Agent Skill 用来让 AI / Agent 按本仓库约定使用 `@heybox/hb-sdk` 和配套 `hb-sdk` CLI，包括 iframe 小程序接入、`ready`、用户信息、登录、事件、CLI 创建模板、`hb-sdk dev` 本地调试、CLI 登录态、协议边界和常见错误处理。
+- [用户与登录](./llms/guide/auth.md): 用户与授权模块当前分工：
+- [CLI 与本地 mock 调试](./llms/guide/cli.md): `@heybox/hb-sdk` 同时提供 iframe 内使用的 SDK 和配套 `hb-sdk` CLI。CLI 负责项目模板、本地 Vite 服务、浏览器 mock runtime host 和 CLI 自己的 Heybox 登录缓存；它不是 iframe SDK 登录态的替代品。
+- [错误处理](./llms/guide/error-handling.md): SDK 对外抛出的标准错误类型是 `HbMiniProgramSDKError`。
+- [安装与运行环境](./llms/guide/installation.md): 如果用户小程序只是普通展示页面，不调用黑盒开放能力，也不监听 SDK 生命周期事件，可以不安装、不引用、不初始化 `@heybox/hb-sdk`。父容器仍可能在 URL 上注入 `hb_mini_bridge_nonce`，业务页可以直接忽略。
+- [事件与生命周期](./llms/guide/lifecycle.md): SDK 通过 `on` 监听父容器派发的小程序生命周期和业务事件。
+- [快速开始](./llms/guide/quick-start.md): 如果页面不需要黑盒开放能力，可以不接入 SDK。这是一条需要用户能力时的最短接入路径：等待 SDK 完成握手，然后读取当前用户登录态。
+## Recipes
+- [独立 SDK 实例](./llms/recipes/custom-instance.md): 大多数业务页使用默认单例即可。只有在需要隔离上下文时，再创建独立实例。
+- [登录门禁](./llms/recipes/login-gate.md): 当业务动作必须登录后才能继续时，可以把登录态判断收敛成 `ensureLogin`。
+## Optional
+- Full markdown mirrors for the docs site are available under `./llms/guide/`, `./llms/reference/`, and `./llms/recipes/`.
+```