@heybox/hb-sdk 0.8.0-alpha → 0.8.0-alpha.3

package/skill/scripts/sync-references.mjs

@@ -1,794 +0,0 @@
-#!/usr/bin/env node
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import process from 'node:process';
-import ts from 'typescript';
-import { extractSection, replaceRequiredSection } from './markdown-sections.mjs';
-import { createSkillContentHash, createSkillManifest, normalizeSkillManifest } from './skill-metadata.mjs';
-
-const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-const skillRoot = path.resolve(scriptDir, '..');
-const referencesRoot = path.join(skillRoot, 'references');
-const repoRoot = findRepoRoot(process.cwd()) ?? findRepoRoot(skillRoot);
-const checkMode = process.argv.includes('--check');
-const TEXT_FILE_RE = /\.(?:md|mjs|js|cjs|ts|tsx|json|txt|sh|yaml|yml)$/i;
-
-if (!repoRoot) {
-  console.error(
-    'Cannot sync hb-sdk references outside the heybox-webapp repository. Run this script from a checkout that contains packages/hb-sdk/package.json.',
-  );
-  process.exit(1);
-}
-
-function findRepoRoot(startDir) {
-  let dir = path.resolve(startDir);
-  while (true) {
-    if (existsSync(path.join(dir, 'package.json')) && existsSync(path.join(dir, 'packages/hb-sdk/package.json'))) {
-      return dir;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
-
-function read(relativePath) {
-  return readFileSync(path.join(repoRoot, relativePath), 'utf8').trimEnd();
-}
-
-function fenced(language, value) {
-  const content = value.trimEnd();
-  const longestFence = Math.max(2, ...Array.from(content.matchAll(/`{3,}/g), (match) => match[0].length));
-  const fence = '`'.repeat(longestFence + 1);
-  return `${fence}${language}\n${content}\n${fence}`;
-}
-
-function header(title, sources) {
-  return [
-    `# ${title}`,
-    '',
-    '> 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',
-    '',
-    ...sources.map((source) => `- ${source}`),
-    '',
-  ].join('\n');
-}
-
-function frontmatterless(markdown) {
-  return markdown.replace(/^---\n[\s\S]*?\n---\n/, '').trimEnd();
-}
-
-function rewriteBundledRecipeLinks(markdown) {
-  return markdown
-    .replaceAll('(../recipes/custom-instance)', '(#custom-instance-recipe)')
-    .replaceAll('(../reference/protocol/interfaces/MiniProgramEventPayloadMap)', '(api-root.md)')
-    .replaceAll('(../reference/protocol/types/#miniprogrameventname)', '(api-root.md)')
-    .replaceAll('(../reference/root/classes/HbMiniProgramSDKError)', '(api-root.md)')
-    .replaceAll('(../reference/root/classes/HbMiniProgramNetworkError)', '(api-root.md)');
-}
-
-function rewriteBundledCliLinks(markdown) {
-  return markdown.replaceAll('(./mini-program-publishing-rules)', '(https://docs.xiaoheihe.cn/hb_sdk/guide/mini-program-publishing-rules)');
-}
-
-function rewriteBundledProtocolIndexLinks(markdown) {
-  return markdown
-    .replaceAll('(./root/)', '(api-root.md)')
-    .replaceAll('(./protocol/)', '(#public-protocol-entrypoint)')
-    .replaceAll('(./compatibility)', '(https://docs.xiaoheihe.cn/hb_sdk/reference/compatibility)')
-    .replaceAll('](/reference/', '](https://docs.xiaoheihe.cn/hb_sdk/reference/')
-    .replaceAll('(./miniapp-publish/)', '(https://open.xiaoheihe.cn/docs/hb_sdk/reference/miniapp-publish/)')
-    .replaceAll('(./vite/)', '(https://open.xiaoheihe.cn/docs/hb_sdk/reference/vite/)')
-    .replaceAll('(./runtime/)', '(https://docs.xiaoheihe.cn/hb_sdk/reference/runtime/)')
-    .replaceAll('(../guide/)', '(recipes.md)');
-}
-
-const INTERNAL_PROTOCOL_DIAGNOSTIC_EXPORTS = new Set([
-  'RUNTIME_LOCATION_PROBE_METHOD',
-  'RuntimeLocationProbePayload',
-  'SDK_CSP_VIOLATION_METHOD',
-  'SDK_LOCATION_REPORT_METHOD',
-  'SDKCSPBlockedResourceType',
-  'SDKCSPViolationPayload',
-  'SDKLocationReportPayload',
-  'SDKLocationReportTrigger',
-]);
-
-function omitNamedExports(source, omittedNames) {
-  const sourceFile = ts.createSourceFile('protocol.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-  const lineStarts = sourceFile.getLineStarts();
-  const removals = [];
-
-  for (const statement of sourceFile.statements) {
-    if (!ts.isExportDeclaration(statement) || !statement.exportClause || !ts.isNamedExports(statement.exportClause)) {
-      continue;
-    }
-
-    for (const element of statement.exportClause.elements) {
-      if (!omittedNames.has(element.name.text)) continue;
-
-      const { line } = sourceFile.getLineAndCharacterOfPosition(element.getStart(sourceFile));
-      const start = lineStarts[line];
-      const end = lineStarts[line + 1] ?? source.length;
-      const lineText = source.slice(start, end).trim();
-      const elementText = element.getText(sourceFile);
-
-      if (lineText !== `${elementText},` && lineText !== elementText) {
-        throw new Error(`Internal protocol export must occupy its own line: ${element.name.text}`);
-      }
-      removals.push({ start, end });
-    }
-  }
-
-  return removals
-    .sort((left, right) => right.start - left.start)
-    .reduce((result, { start, end }) => `${result.slice(0, start)}${result.slice(end)}`, source);
-}
-
-function contents(items) {
-  return ['', '## Contents', '', ...items.map(([title, anchor]) => `- [${title}](#${anchor})`), ''].join('\n');
-}
-
-function toPosix(value) {
-  return value.split(path.sep).join('/');
-}
-
-function walkDistributableSkillFiles(dir, relativeBase = '') {
-  const out = [];
-
-  if (!existsSync(dir)) {
-    return out;
-  }
-
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (entry.name.startsWith('.')) {
-      continue;
-    }
-
-    const fullPath = path.join(dir, entry.name);
-    const relativePath = toPosix(path.join(relativeBase, entry.name));
-
-    if (entry.isDirectory()) {
-      out.push(...walkDistributableSkillFiles(fullPath, relativePath));
-      continue;
-    }
-
-    if (!entry.isFile()) {
-      continue;
-    }
-
-    if (relativePath === 'skill.json' || /\.zip$/i.test(relativePath) || !TEXT_FILE_RE.test(relativePath)) {
-      continue;
-    }
-
-    out.push(relativePath);
-  }
-
-  return out;
-}
-
-function readGeneratedOrDiskSkillFile(relativePath, generatedReferences) {
-  if (relativePath.startsWith('references/')) {
-    const generated = generatedReferences.get(relativePath.slice('references/'.length));
-
-    if (generated !== undefined) {
-      return `${generated.trimEnd()}\n`;
-    }
-  }
-
-  return readFileSync(path.join(skillRoot, ...relativePath.split('/')));
-}
-
-function createCurrentSkillManifest(generatedReferences) {
-  const distributableFiles = [
-    'SKILL.md',
-    ...walkDistributableSkillFiles(path.join(skillRoot, 'references'), 'references'),
-    ...walkDistributableSkillFiles(path.join(skillRoot, 'scripts'), 'scripts'),
-    ...walkDistributableSkillFiles(path.join(skillRoot, 'assets'), 'assets'),
-  ];
-  const fileEntries = Array.from(new Set(distributableFiles))
-    .sort((left, right) => left.localeCompare(right))
-    .map((relativePath) => ({
-      path: relativePath,
-      content: readGeneratedOrDiskSkillFile(relativePath, generatedReferences),
-    }));
-
-  return createSkillManifest({
-    contentHash: createSkillContentHash(fileEntries),
-    sdkVersion: packageJson.version,
-  });
-}
-
-const packageJson = JSON.parse(read('packages/hb-sdk/package.json'));
-const rootEntry = read('packages/hb-sdk/src/index.ts');
-const protocolEntry = read('packages/hb-sdk/src/protocol.ts');
-const viteEntry = read('packages/hb-sdk/src/vite/index.ts');
-const cliEntry = read('packages/hb-sdk/src/cli/index.ts');
-const readme = read('packages/hb-sdk/README.md');
-const cliGuide = frontmatterless(read('apps/docs/hb-sdk/guide/cli.md'));
-const quickStart = frontmatterless(read('apps/docs/hb-sdk/guide/quick-start.md'));
-const authGuide = frontmatterless(read('apps/docs/hb-sdk/guide/auth.md'));
-const authGuideForSkill = replaceRequiredSection(
-  authGuide,
-  '## 后端 OpenAPI',
-  [
-    '## 后端 OpenAPI',
-    '',
-    '开发者服务端按[在线用户身份与登录文档](https://docs.xiaoheihe.cn/hb_sdk/guide/auth)完成授权码交换和用户读取。小程序页面只提交 `auth.login()` 返回的短期 code，不持有服务端密钥、access token 或认证 header；Agent Skill 不分发服务端凭据操作示例。',
-  ].join('\n'),
-);
-const lifecycleGuide = frontmatterless(read('apps/docs/hb-sdk/guide/lifecycle.md'));
-const errorGuide = frontmatterless(read('apps/docs/hb-sdk/guide/error-handling.md'));
-const loginGate = frontmatterless(read('apps/docs/hb-sdk/recipes/login-gate.md'));
-const communityShare = frontmatterless(read('apps/docs/hb-sdk/recipes/community-share.md'));
-const customInstance = frontmatterless(read('apps/docs/hb-sdk/recipes/custom-instance.md'));
-const referenceHome = frontmatterless(read('apps/docs/hb-sdk/reference/index.md'));
-const publicCapabilities = extractSection(readme, '## 能力概览');
-const capabilityBoundaries = extractSection(readme, '## 关键约束');
-const leaderboardSection = extractSection(readme, '## 云端排行榜');
-const publicProtocolEntry = omitNamedExports(protocolEntry, INTERNAL_PROTOCOL_DIAGNOSTIC_EXPORTS);
-const manifestSection = extractSection(cliGuide, '## 生产构建');
-const cliCreateSection = extractSection(cliGuide, '## 创建工坊小程序');
-const cliDevSection = extractSection(cliGuide, '## 推荐调试流程');
-const cliBuildSection = extractSection(cliGuide, '## 生产构建');
-const cliDeploySection = extractSection(cliGuide, '## 部署发布');
-const cliRemoteSection = extractSection(cliGuide, '## 远端管理命令');
-const cliLoginSection = extractSection(cliGuide, '## CLI 登录态');
-const cliDoctorSection = extractSection(cliGuide, '## Agent Skill doctor');
-const cliUpdateSection = extractSection(cliGuide, '## 版本提醒');
-const cliCommandSurface = `hb-sdk create <project-name>
-hb-sdk dev [--port <port>] [--browser-dev-host-port <port>] [--no-open]
-hb-sdk build [--env <name>] [--verbose]
-hb-sdk login
-hb-sdk login status
-hb-sdk login clear
-hb-sdk doctor
-hb-sdk remote access
-hb-sdk remote entity list
-hb-sdk remote entity current
-hb-sdk remote entity switch <entity-id>
-hb-sdk remote list [--status <status>] [--keyword <text>]
-hb-sdk remote create [--yes] [--force-bind]
-hb-sdk remote bind <mini-program-id> [--force]
-hb-sdk remote info
-hb-sdk remote allowlist list
-hb-sdk remote allowlist add <heybox-id...>
-hb-sdk remote allowlist remove <heybox-id...>
-hb-sdk remote allowlist set <heybox-id...>
-hb-sdk remote deploy --release-note <text> [--from-version <version>] [--auto-publish]
-hb-sdk remote versions
-hb-sdk remote preview <version>
-hb-sdk remote release <version> [--yes]
-hb-sdk remote withdraw <version> [--yes] [--reason <text>]
-hb-sdk remote take-down [--yes]
-hb-sdk remote reopen [--yes]
-hb-sdk remote square hide [--yes]
-hb-sdk remote square show
-
-Removed: hb-sdk deploy`;
-
-const cliRemoteEntitySection = `Developer account selection lives under \`hb-sdk remote entity\`:
-
-${fenced(
-  'bash',
-  `hb-sdk remote entity list
-hb-sdk remote entity current
-hb-sdk remote entity switch <entity-id>`,
-)}
-
-Remote management commands use the current developer account. Use \`current\` to confirm it and \`switch\` to change it before creating, binding, or publishing a mini-program.`;
-
-const cliRemoteEntityDeploySection = `Before publishing, \`hb-sdk remote deploy\` verifies that the bound mini-program belongs to the current developer account. If it does not, the command stops and asks the user to switch accounts.`;
-
-const files = new Map();
-
-files.set(
-  'api-root.md',
-  `${header('Root API reference', [
-    'packages/hb-sdk/package.json',
-    'packages/hb-sdk/src/index.ts',
-    'packages/hb-sdk/src/vite/index.ts',
-    'packages/hb-sdk/README.md',
-    'apps/docs/hb-sdk/guide/quick-start.md',
-    'apps/docs/hb-sdk/guide/error-handling.md',
-    'apps/docs/hb-sdk/guide/lifecycle.md',
-    'apps/docs/hb-sdk/guide/cli.md',
-  ])}${contents([
-    ['Package metadata', 'package-metadata'],
-    ['Public root entrypoint', 'public-root-entrypoint'],
-    ['Vite plugin export', 'vite-plugin-export'],
-    ['App-facing concepts', 'app-facing-concepts'],
-    ['Public modules', 'public-modules'],
-    ['Cloud leaderboard', 'cloud-leaderboard'],
-  ])}## Package metadata
-
-- Package: \`${packageJson.name}\`
-- Version at generation time: \`${packageJson.version}\`
-- Public root export: \`@heybox/hb-sdk\`
-- Protocol export: \`@heybox/hb-sdk/protocol\`
-- Vite plugin export: \`@heybox/hb-sdk/vite\`
-
-## Public root entrypoint
-
-${fenced('ts', rootEntry)}
-
-## Vite plugin export
-
-Use \`@heybox/hb-sdk/vite\` only in \`vite.config.ts\`. Do not import it from iframe mini-program business code.
-
-${fenced('ts', viteEntry)}
-
-${manifestSection}
-
-## App-facing concepts
-
-${quickStart}
-
-${rewriteBundledRecipeLinks(errorGuide)}
-
-## Public modules
-
-${publicCapabilities}
-
-${rewriteBundledRecipeLinks(lifecycleGuide)}
-
-${leaderboardSection}
-`,
-);
-
-files.set(
-  'api-protocol.md',
-  `${header('Protocol API reference', ['packages/hb-sdk/src/protocol.ts', 'apps/docs/hb-sdk/reference/index.md'])}${contents([
-    ['Host/runtime-only warning', 'hostruntime-only-warning'],
-    ['Public protocol entrypoint', 'public-protocol-entrypoint'],
-    ['Generated reference index', 'generated-reference-index'],
-  ])}## Host/runtime-only warning
-
-New parent-container Host, \`@heybox/hb-sdk-runtime\`, bridge-server, and protocol-contract maintenance must import wire contracts directly from \`@heybox/hb-sdk-protocol\`. Use \`@heybox/hb-sdk/protocol\` only for explicitly retained existing compatibility consumers. Iframe mini-program business code must use root SDK APIs and must not construct bridge envelopes, nonce handling, or raw \`postMessage\` flows.
-
-## Public protocol entrypoint
-
-${fenced('ts', publicProtocolEntry)}
-
-## Generated reference index
-
-${rewriteBundledProtocolIndexLinks(referenceHome)}
-`,
-);
-
-files.set(
-  'cli.md',
-  `${header('CLI reference', [
-    '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/build.ts',
-    'packages/hb-sdk/src/cli/commands/login.ts',
-    'apps/docs/hb-sdk/guide/cli.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 debugging', 'local-debugging'],
-    ['Production build', 'production-build'],
-    ['Deploy and publish', 'deploy-and-publish'],
-    ['Developer account scope', 'developer-account-scope'],
-    ['Remote management commands', 'remote-management-commands'],
-    ['CLI login', 'cli-login'],
-    ['Agent Skill doctor', 'agent-skill-doctor'],
-    ['Update reminders', 'update-reminders'],
-  ])}## When to use the CLI
-
-Use the bundled \`hb-sdk\` CLI to create a workshop mini-program, open the local debugging page, test in the Heybox Mac or mobile App, or manage and publish a remote mini-program.
-
-\`hb-sdk login\` is for development and publishing commands only. It does not authorize mini-program users and does not change \`auth.login()\`, \`user.getInfo()\`, or \`network.request()\` inside a mini-program.
-
-## Command surface
-
-${fenced('text', cliCommandSurface)}
-
-Top-level \`hb-sdk deploy\` has been hard-cut and must not be documented as a valid compatibility alias. Keep \`hb-sdk login\` top-level because it manages CLI login state, not a specific remote mini-program.
-
-## Create a mini-program template
-
-${cliCreateSection}
-
-Agent rules:
-
-- Prefer \`hb-sdk create <project-name>\` for a new workshop mini-program.
-- 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 debugging
-
-${cliDevSection}
-
-Use \`hb-sdk dev\` to open the local debugging page after CLI login and project binding are complete. Missing login, binding, or remote Dev Context stops before Vite and the debugging services start. The "Mobile App" QR code opens it in the phone App after a LAN interface is selected. The phone and computer must be on the same LAN.
-
-Browser Mock uses the Node \`hb-sdk login\` session to send Host \`heybox-session\` requests. Mini-program code must still call \`auth.login()\`; the debug page only shows an authorization dialog. Never copy pkey, cookies, tokens, or credential-bearing URLs into page JavaScript or logs. Phone debugging continues to use the App login, not the CLI session.
-
-## Production build
-
-${cliBuildSection}
-
-Agent rules:
-
-- Use \`hb-sdk build [--env <name>] [--verbose]\` as the recommended production build entry.
-- Require explicit \`miniappManifest()\` configuration and keep typechecking in the project's \`scripts.build\`.
-- Do not claim \`hb-sdk build\` needs login, binding, or network access, and do not invent unsupported build flags.
-- Existing \`vite build\` projects remain compatible and must not be auto-migrated.
-
-## Deploy and publish
-
-${rewriteBundledCliLinks(cliDeploySection)}
-
-${cliRemoteEntityDeploySection}
-
-Agent rules:
-
-- Use \`hb-sdk remote deploy --release-note <text>\` for normal build, upload, and submit-audit flows.
-- Use \`hb-sdk remote deploy --from-version <version> --release-note <text>\` to reuse a remote history artifact.
-- If the bound mini-program does not belong to the current developer account, stop and ask the user to switch accounts.
-- Never recommend top-level \`hb-sdk deploy\`; it has been removed rather than retained as a compatibility alias.
-- After non-auto deploy succeeds, suggest \`hb-sdk remote versions\` and then \`hb-sdk remote release <version>\` after approval. Do not send the user to Open for manual publish when the CLI command exists.
-- Use \`hb-sdk remote allowlist add <heybox_id>\` when preview access needs to be granted.
-
-## Developer account scope
-
-${cliRemoteEntitySection}
-
-Agent rules:
-
-- Treat the current developer account as the scope for remote create, bind, deploy, list, access, versions, preview, release, withdraw, take-down, reopen, and square-display workflows.
-- Use \`hb-sdk remote entity current\` when a user needs to confirm which entity create/deploy will use.
-- Use \`hb-sdk remote entity switch <entity-id>\` to change entity scope. Do not recommend \`--entity-id\` or an environment variable as a remote command override.
-- \`hb-sdk remote list\` lists mini-programs in the current entity scope only; do not promise cross-entity aggregation.
-
-## Remote management commands
-
-${cliRemoteSection}
-
-Agent rules:
-
-- Use \`hb-sdk remote entity list/current/switch\` for developer entity inspection and switching.
-- Use \`hb-sdk remote create\` for create-and-bind and \`hb-sdk remote bind <mini-program-id>\` for binding an existing manageable remote mini-program.
-- Do not require or submit mini-program name/icon/cover from CLI; maintain them on Open version publish. CLI project configuration contains only \`package.json.heybox.miniProgramId\`.
-- Explain that \`remote create\` creates under the current entity and that multi-entity non-TTY usage must confirm with \`--yes\`; \`--yes\` confirms current-entity usage but does not switch entities.
-- Explain that \`remote bind\` verifies the mini-program is manageable by the current entity and does not write \`package.json.heybox.miniProgramId\` on entity mismatch.
-- Use \`hb-sdk remote info\`, \`hb-sdk remote access\`, \`hb-sdk remote list\`, \`hb-sdk remote versions\`, \`hb-sdk remote preview <version>\`, \`hb-sdk remote square show/hide\`, and \`hb-sdk remote allowlist ...\` instead of sending users to Open when a matching CLI command exists.
-- Do not expose a CLI basic-info update command; mini-program name and image changes must go through version audit.
-- Treat \`hb-sdk remote list\` as discovery only. Dangerous write commands still target the bound mini-program from \`package.json.heybox.miniProgramId\`.
-- Require confirmation or \`--yes\` for \`hb-sdk remote release\`, \`hb-sdk remote withdraw\`, \`hb-sdk remote take-down\`, \`hb-sdk remote reopen\`, and \`hb-sdk remote square hide\`.
-- Use \`--json\` for script consumption and keep stdout as exactly one JSON object.
-
-## CLI login
-
-${cliLoginSection}
-
-Agent rules:
-
-- Keep CLI login separate from the mini-program user 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
-
-${cliDoctorSection}
-
-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 \`${packageJson.name}@latest\` before reinstalling the skill.
-
-## Update reminders
-
-${cliUpdateSection}
-
-`,
-);
-
-files.set(
-  'recipes.md',
-  `${header('Recipes', [
-    'apps/docs/hb-sdk/guide/quick-start.md',
-    'apps/docs/hb-sdk/guide/auth.md',
-    'apps/docs/hb-sdk/guide/lifecycle.md',
-    'apps/docs/hb-sdk/guide/error-handling.md',
-    'apps/docs/hb-sdk/recipes/login-gate.md',
-    'apps/docs/hb-sdk/recipes/community-share.md',
-    'apps/docs/hb-sdk/recipes/custom-instance.md',
-  ])}${contents([
-    ['Quick start', 'quick-start'],
-    ['User and login', 'user-and-login'],
-    ['Lifecycle events', 'lifecycle-events'],
-    ['Error handling', 'error-handling'],
-    ['Login gate recipe', 'login-gate-recipe'],
-    ['Community share recipe', 'community-share-recipe'],
-    ['Custom instance recipe', 'custom-instance-recipe'],
-  ])}## Quick start
-
-${rewriteBundledRecipeLinks(quickStart)}
-
-## User and login
-
-${rewriteBundledRecipeLinks(authGuideForSkill)}
-
-## Lifecycle events
-
-${rewriteBundledRecipeLinks(lifecycleGuide)}
-
-## Error handling
-
-${rewriteBundledRecipeLinks(errorGuide)}
-
-## Login gate recipe
-
-${rewriteBundledRecipeLinks(loginGate)}
-
-## Community share recipe
-
-${rewriteBundledRecipeLinks(communityShare)}
-
-## Custom instance recipe
-
-${rewriteBundledRecipeLinks(customInstance)}
-`,
-);
-
-files.set(
-  'safety-boundaries.md',
-  `${header('Safety boundaries', ['packages/hb-sdk/README.md', 'apps/docs/hb-sdk/guide/auth.md'])}## Required boundaries
-
-${capabilityBoundaries}
-
-## Agent rules
-
-- Do not instruct mini-program code to read, extract, forward, store, or depend on token, cookie, phone number, or private credentials.
-- Negative safety statements that explain the SDK does not expose token/cookie/private credentials are correct and should be preserved.
-- Do not use raw share protocol fields, JS callbacks, activity reporting, direct post publishing, custom buttons, or upload-only flows. Public \`share.*({ post })\` options only preset an editable client post flow.
-- Do not use storage delete, clear, info listing, or global Heybox client storage access.
-- Do not pass host-only protocol fields through \`network.request\`.
-- Do not build raw \`postMessage\` bridge flows in iframe business code.
-- Do not fetch deployed \`dist/manifest.json\` from business code; it is a build artifact for the release pipeline, not a CDN runtime asset.
-- Do not import from internal hb-sdk implementation paths; only use documented package entrypoints.
-- Browser Dev Host may use the Node \`hb-sdk login\` session to send Host \`heybox-session\` requests. Never expose pkey, cookies, tokens, or credential-bearing URLs to browser JavaScript, page UI, or logs. Mini-program code must still call \`auth.login()\`.
-`,
-);
-
-files.set(
-  'llms-index.md',
-  `${header('LLM documentation index', [
-    'apps/docs/hb-sdk/guide/**',
-    'apps/docs/hb-sdk/recipes/**',
-    'apps/docs/hb-sdk/reference/**',
-    'packages/hb-sdk/src/**',
-  ])}## Offline references
-
-The bundled references are generated directly from hand-maintained docs, generated API owner sources, and SDK/CLI sources. They do not depend on the docs site's \`.vitepress/public/llms\` mirrors.
-
-- Root SDK and Vite API: \`references/api-root.md\`
-- Host/runtime protocol API: \`references/api-protocol.md\`
-- CLI and local development: \`references/cli.md\`
-- Common flows: \`references/recipes.md\`
-- Security and capability limits: \`references/safety-boundaries.md\`
-- Examples and evaluation: \`references/examples.md\`, \`references/smoke-evaluation.md\`
-
-## Online supplement
-
-Online \`llms.txt\` and markdown mirrors are optional supplements, not prerequisites for offline Skill use. Their canonical public URL is not frozen: on 2026-07-10 \`https://docs.xiaoheihe.cn/hb_sdk/llms.txt\` returned 404 and the legacy URL fetch timed out. Do not claim either endpoint is available without a fresh successful response.
-`,
-);
-
-files.set(
-  'examples.md',
-  `${header('Smoke examples and anti-examples', [
-    'packages/hb-sdk/README.md',
-    'apps/docs/hb-sdk/guide/**',
-    'apps/docs/hb-sdk/recipes/**',
-  ])}## Positive examples
-
-### Gesture-gated control handshake state
-
-${fenced(
-  'ts',
-  `import hbSDK, { type MiniProgramSDKHandshakeState } from '@heybox/hb-sdk';
-
-let handshakeState: MiniProgramSDKHandshakeState = hbSDK.getHandshakeState();
-const stopHandshakeState = hbSDK.onHandshakeStateChange((state) => {
-  handshakeState = state;
-  setLoginButtonDisabled(state.status !== 'ready');
-});
-
-export function disposePage() {
-  stopHandshakeState();
-}
-
-export async function loginFromUserAction() {
-  if (handshakeState.status !== 'ready') return;
-  return hbSDK.auth.login();
-}
-
-function setLoginButtonDisabled(disabled: boolean) {
-  document.querySelector('button')?.toggleAttribute('disabled', disabled);
-}`,
-)}
-
-### Current user for a network-disabled mini-program
-
-${fenced(
-  'ts',
-  `import { user } from '@heybox/hb-sdk';
-
-export async function getCurrentUser() {
-  const result = await user.getInfo();
-  return result.userInfo?.app_user_id;
-}`,
-)}
-
-### Developer server session for a network-enabled mini-program
-
-${fenced(
-  'ts',
-  `import { auth, network, HbMiniProgramSDKError } from '@heybox/hb-sdk';
-
-export async function createServerSessionFromUserAction() {
-  try {
-    const result = await auth.login({ scopes: ['profile'] });
-    await exchangeCodeWithDeveloperServer(result.code);
-    return { status: 'ready' as const };
-  } catch (error) {
-    if (error instanceof HbMiniProgramSDKError && error.code === 'AUTHORIZATION_CANCELLED') {
-      return { status: 'cancelled' as const };
-    }
-    throw error;
-  }
-}
-
-async function exchangeCodeWithDeveloperServer(code: string) {
-  await network.request({
-    url: 'https://api.example.com/session/heybox',
-    method: 'POST',
-    data: { code },
-  });
-}`,
-)}
-
-### Network request
-
-${fenced(
-  'ts',
-  `import { network, HbMiniProgramNetworkError, HbMiniProgramSDKError } from '@heybox/hb-sdk';
-
-try {
-  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);
-
-  // form POST only: App Host does not support multipart/form-data
-  await network.request({
-    url: 'https://api.example.com/form',
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8',
-    },
-    data: new URLSearchParams({ gameId: '3', roleId: '1' }).toString(),
-  });
-} catch (error) {
-  if (error instanceof HbMiniProgramNetworkError) {
-    // Target HTTP non-2xx, or host-side network_error (message says so)
-    console.warn(error.status, error.message, error.data);
-  } else if (error instanceof HbMiniProgramSDKError) {
-    // e.g. INVALID_PARAMS for unsupported multipart shape
-    console.warn(error.code, error.message);
-  }
-}`,
-)}
-
-### Host/runtime protocol import
-
-${fenced(
-  'ts',
-  `import { NETWORK_REQUEST_METHOD, type NetworkRequestPayload } from '@heybox/hb-sdk-protocol';
-
-// New Host/runtime integration only. Existing released consumers may retain @heybox/hb-sdk/protocol until explicitly migrated.
-export function canHandleNetwork(method: string): method is typeof NETWORK_REQUEST_METHOD {
-  return method === NETWORK_REQUEST_METHOD;
-}`,
-)}
-
-### CLI local mock development
-
-${fenced(
-  'bash',
-  `hb-sdk create my-miniapp
-cd my-miniapp
-npm install
-npm run dev
-
-# In an existing project:
-hb-sdk dev`,
-)}
-
-### CLI login cache
-
-${fenced(
-  'bash',
-  `hb-sdk login
-hb-sdk login status
-hb-sdk login clear`,
-)}
-
-### Vite manifest plugin
-
-${fenced(
-  'ts',
-  `import { miniappManifest } from '@heybox/hb-sdk/vite';
-import { defineConfig } from 'vite';
-
-export default defineConfig({
-  base: './',
-  plugins: [miniappManifest({ platforms: ['android', 'ios', 'ohos'] })],
-});`,
-)}
-
-## Negative examples
-
-- Do not import from internal hb-sdk implementation paths.
-- The non-replayed \`ready\` lifecycle event is only an edge notification. After a duplicate handshake it may repeat; never treat it as current state, and query or subscribe to the persistent state APIs instead.
-- Do not wait for handshake inside a gesture-gated click handler; keep the control disabled until the persistent state is \`ready\`.
-- 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 send \`multipart/form-data\` (or handcrafted multipart bodies) through \`network.request\`; use form-urlencoded string body or a dedicated upload capability.
-- 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.
-- Do not import \`@heybox/hb-sdk/vite\` from iframe business code or fetch a deployed \`manifest.json\` directly.
-`,
-);
-
-const skillManifest = normalizeSkillManifest(createCurrentSkillManifest(files));
-
-if (!existsSync(referencesRoot)) mkdirSync(referencesRoot, { recursive: true });
-
-let changed = false;
-for (const [fileName, content] of files.entries()) {
-  const target = path.join(referencesRoot, fileName);
-  const normalized = `${content.trimEnd()}\n`;
-  const current = existsSync(target) ? readFileSync(target, 'utf8') : '';
-  if (current !== normalized) {
-    changed = true;
-    if (!checkMode) writeFileSync(target, normalized);
-    console.error(`${checkMode ? 'outdated' : 'updated'} ${path.relative(repoRoot, target)}`);
-  }
-}
-
-const skillManifestPath = path.join(skillRoot, 'skill.json');
-const currentSkillManifest = existsSync(skillManifestPath) ? readFileSync(skillManifestPath, 'utf8') : '';
-if (currentSkillManifest !== skillManifest) {
-  changed = true;
-  if (!checkMode) writeFileSync(skillManifestPath, skillManifest);
-  console.error(`${checkMode ? 'outdated' : 'updated'} ${path.relative(repoRoot, skillManifestPath)}`);
-}
-
-if (checkMode && changed) {
-  console.error(
-    `hb-sdk skill references are out of date. Run \`node ${path
-      .relative(repoRoot, fileURLToPath(import.meta.url))
-      .split(path.sep)
-      .join('/')}\`.`,
-  );
-  process.exit(1);
-}
-
-console.log(JSON.stringify({ ok: true, changed, references: [...files.keys()], skillVersion: JSON.parse(skillManifest).skillVersion }));