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

package/skill/scripts/sync-references.mjs

@@ -0,0 +1,541 @@
+#!/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 { 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 extractSection(markdown, heading) {
+  const lines = markdown.split('\n');
+  const start = lines.findIndex(line => line.trim() === heading);
+  if (start === -1) return '';
+  const level = heading.match(/^#+/)?.[0].length ?? 2;
+  const out = [lines[start]];
+  let fenceChar = '';
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+
+    if (fenceChar) {
+      out.push(line);
+      if (fenceMatch?.[1]?.startsWith(fenceChar)) {
+        fenceChar = '';
+      }
+      continue;
+    }
+
+    if (fenceMatch) {
+      fenceChar = fenceMatch[1][0];
+      out.push(line);
+      continue;
+    }
+
+    const headingMatch = line.match(/^(#+)\s/);
+    if (headingMatch && headingMatch[1].length <= level) break;
+    out.push(line);
+  }
+  return out.join('\n').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 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 cliEntry = read('packages/hb-sdk/src/cli/index.ts');
+const cliTemplateReadme = read('packages/hb-sdk/src/cli/templates/vue3-vite-ts/README.md.ejs');
+const readme = read('packages/hb-sdk/README.md');
+const cliGuide = frontmatterless(read('apps/h5/docs/hb_sdk/src/guide/cli.md'));
+const llmsTxt = read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms.txt');
+const quickStart = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/quick-start.md')); 
+const authGuide = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md')); 
+const lifecycleGuide = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/lifecycle.md')); 
+const errorGuide = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/error-handling.md')); 
+const loginGate = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/login-gate.md')); 
+const customInstance = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/custom-instance.md')); 
+const referenceHome = frontmatterless(read('apps/h5/docs/hb_sdk/src/.vuepress/public/llms/reference/README.md'));
+
+const quickStartSection = extractSection(readme, '## 快速开始');
+const runtimeEnvironment = extractSection(readme, '## 运行环境');
+const publicCapabilities = extractSection(readme, '## 常用能力');
+const lifecycleEvents = extractSection(readme, '## 生命周期事件');
+const standardErrors = extractSection(readme, '## 错误处理');
+const sdkRuntimeRelation = extractSection(readme, '## SDK 与 Runtime');
+const capabilityBoundaries = extractSection(readme, '## 能力边界');
+const cliSummarySection = extractSection(readme, '## CLI');
+const repositoryDevelopment = extractSection(readme, '## 本仓库开发');
+const cliCreateSection = extractSection(cliGuide, '## 创建外部小程序模板');
+const cliDevSection = [
+  extractSection(cliGuide, '## 本地开发模式'),
+  extractSection(cliGuide, '## Mock runtime 边界'),
+].filter(Boolean).join('\n\n');
+const cliLoginSection = extractSection(cliGuide, '## CLI 登录态');
+const cliDoctorSection = extractSection(cliGuide, '## Agent Skill doctor');
+const cliUpdateSection = extractSection(cliGuide, '## 版本提醒');
+
+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/README.md',
+])}${contents([
+  ['Package metadata', 'package-metadata'],
+  ['Public root entrypoint', 'public-root-entrypoint'],
+  ['App-facing concepts', 'app-facing-concepts'],
+  ['Public modules', 'public-modules'],
+])}## Package metadata
+
+- Package: \`${packageJson.name}\`
+- Version at generation time: \`${packageJson.version}\`
+- Public root export: \`@heybox/hb-sdk\`
+- Protocol export: \`@heybox/hb-sdk/protocol\`
+
+## Public root entrypoint
+
+${fenced('ts', rootEntry)}
+
+## App-facing concepts
+
+${quickStartSection}
+
+${runtimeEnvironment}
+
+${standardErrors}
+
+## Public modules
+
+${publicCapabilities}
+
+${lifecycleEvents}
+`);
+
+files.set('api-protocol.md', `${header('Protocol API reference', [
+  'packages/hb-sdk/src/protocol.ts',
+  'packages/hb-sdk/README.md',
+  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/reference/README.md',
+])}${contents([
+  ['Host/runtime-only warning', 'hostruntime-only-warning'],
+  ['Public protocol entrypoint', 'public-protocol-entrypoint'],
+  ['Protocol context', 'protocol-context'],
+  ['Generated reference index', 'generated-reference-index'],
+])}## Host/runtime-only warning
+
+Use \`@heybox/hb-sdk/protocol\` only for parent-container runtime, bridge-server, protocol-contract, or \`@heybox/hb-sdk-runtime\` integration tasks. 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', protocolEntry)}
+
+## Protocol context
+
+${sdkRuntimeRelation}
+
+## Generated reference index
+
+${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/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 \`${packageJson.name}\`. Do not create a second mock runtime package or move CLI guidance outside this package unless the package boundary changes.
+
+## Command surface
+
+${fenced('ts', cliEntry)}
+
+## Create a mini-program template
+
+${cliCreateSection}
+
+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
+
+${cliDevSection}
+
+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
+
+${cliLoginSection}
+
+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
+
+${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.
+- The supported local skill path is \`$CODEX_HOME/skills/hb-sdk/skill.json\`, falling back to \`~/.codex/skills/hb-sdk/skill.json\`.
+
+## Update reminders
+
+${cliUpdateSection}
+
+## Repository validation commands
+
+${repositoryDevelopment}
+
+## Generated template README
+
+${fenced('md', cliTemplateReadme)}
+`);
+
+files.set('recipes.md', `${header('Recipes', [
+  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/quick-start.md',
+  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/auth.md',
+  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/lifecycle.md',
+  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/guide/error-handling.md',
+  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/recipes/login-gate.md',
+  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/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'],
+  ['Custom instance recipe', 'custom-instance-recipe'],
+])}## Quick start
+
+${quickStart}
+
+## User and login
+
+${authGuide}
+
+## Lifecycle events
+
+${lifecycleGuide}
+
+## Error handling
+
+${errorGuide}
+
+## Login gate recipe
+
+${loginGate}
+
+## Custom instance recipe
+
+${customInstance}
+`);
+
+files.set('safety-boundaries.md', `${header('Safety boundaries', [
+  'packages/hb-sdk/README.md',
+  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/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, post publishing, custom buttons, or upload-only flows.
+- Do not use storage delete, clear, info listing, V2, 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 import from internal hb-sdk implementation paths; only use documented package entrypoints.
+`);
+
+files.set('llms-index.md', `${header('LLM documentation index', [
+  '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.
+
+${fenced('md', llmsTxt)}
+`);
+
+files.set('examples.md', `${header('Smoke examples and anti-examples', [
+  'packages/hb-sdk/README.md',
+  'apps/h5/docs/hb_sdk/src/.vuepress/public/llms/',
+])}## Positive examples
+
+### Minimal user info
+
+${fenced('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
+
+${fenced('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
+
+${fenced('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
+
+${fenced('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
+
+${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`)}
+
+## 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.
+`);
+
+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 }));