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

package/skill/scripts/validate-skill.mjs

@@ -1,263 +0,0 @@
-#!/usr/bin/env node
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import process from 'node:process';
-import { HB_SDK_PACKAGE_NAME, HB_SDK_SKILL_NAME, validateSkillManifest } from './skill-metadata.mjs';
-
-const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-const skillRoot = path.resolve(scriptDir, '..');
-const packageRoot = path.resolve(skillRoot, '..');
-const repoRoot = findRepoRoot(process.cwd()) ?? findRepoRoot(skillRoot) ?? process.cwd();
-const errors = [];
-const warnings = [];
-
-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 rel(filePath) {
-  return path.relative(repoRoot, filePath).split(path.sep).join('/');
-}
-
-function skillRel(filePath) {
-  return path.relative(skillRoot, filePath).split(path.sep).join('/');
-}
-
-function fail(message) {
-  errors.push(message);
-}
-
-function warn(message) {
-  warnings.push(message);
-}
-
-function read(filePath) {
-  return readFileSync(filePath, 'utf8');
-}
-
-function walk(dir) {
-  const out = [];
-  for (const entry of readdirSync(dir)) {
-    const fullPath = path.join(dir, entry);
-    const stat = statSync(fullPath);
-    if (stat.isDirectory()) out.push(...walk(fullPath));
-    else out.push(fullPath);
-  }
-  return out;
-}
-
-function parseFrontmatter(markdown) {
-  const match = markdown.match(/^---\n([\s\S]*?)\n---\n/);
-  if (!match) return null;
-  const fields = new Map();
-  for (const line of match[1].split('\n')) {
-    const field = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
-    if (field) fields.set(field[1], field[2].replace(/^['"]|['"]$/g, ''));
-  }
-  return fields;
-}
-
-function validateLocalMarkdownLinks(filePath, markdown) {
-  const linkPattern = /\[[^\]]*\]\(([^)]+)\)/g;
-  for (const match of markdown.matchAll(linkPattern)) {
-    const rawTarget = match[1].trim().replace(/^<|>$/g, '');
-    if (/^(?:https?:|mailto:|#)/i.test(rawTarget)) continue;
-
-    const targetWithoutAnchor = rawTarget.split('#')[0];
-    if (!targetWithoutAnchor) continue;
-
-    const resolved = path.resolve(path.dirname(filePath), targetWithoutAnchor);
-    if (!existsSync(resolved)) {
-      const line = markdown.slice(0, match.index).split('\n').length;
-      fail(`Broken local Markdown link in ${skillRel(filePath)}:${line}: ${rawTarget}`);
-    }
-  }
-}
-
-const requiredFiles = [
-  'SKILL.md',
-  'skill.json',
-  'references/api-root.md',
-  'references/api-protocol.md',
-  'references/cli.md',
-  'references/recipes.md',
-  'references/safety-boundaries.md',
-  'references/llms-index.md',
-  'references/examples.md',
-  'references/smoke-evaluation.md',
-  'scripts/sync-references.mjs',
-  'scripts/check-references.mjs',
-  'scripts/skill-metadata.mjs',
-  'scripts/validate-skill.mjs',
-  'scripts/package-skill.mjs',
-  'scripts/package-skill.sh',
-];
-
-for (const file of requiredFiles) {
-  const absolutePath = path.join(skillRoot, file);
-  if (!existsSync(absolutePath)) fail(`Missing required file: ${rel(absolutePath)}`);
-}
-
-const skillMdPath = path.join(skillRoot, 'SKILL.md');
-const packageJsonPath = path.join(repoRoot, 'packages/hb-sdk/package.json');
-const skillJsonPath = path.join(skillRoot, 'skill.json');
-
-if (existsSync(skillJsonPath) && existsSync(packageJsonPath)) {
-  try {
-    const skillJson = JSON.parse(read(skillJsonPath));
-    const packageJson = JSON.parse(read(packageJsonPath));
-
-    for (const error of validateSkillManifest({ manifest: skillJson, sdkVersion: packageJson.version })) {
-      fail(error);
-    }
-  } catch (error) {
-    fail(`skill.json must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
-  }
-}
-
-if (existsSync(skillMdPath)) {
-  const skillMd = read(skillMdPath);
-  const frontmatter = parseFrontmatter(skillMd);
-  if (!frontmatter) {
-    fail('SKILL.md must start with YAML frontmatter.');
-  } else {
-    const allowedFrontmatter = new Set(['name', 'description']);
-    for (const key of frontmatter.keys()) {
-      if (!allowedFrontmatter.has(key)) fail(`SKILL.md frontmatter must only include name and description; found ${key}.`);
-    }
-    const name = frontmatter.get('name');
-    const description = frontmatter.get('description');
-    if (name !== HB_SDK_SKILL_NAME) fail('SKILL.md frontmatter name must be `hb-sdk`.');
-    if (!description) fail('SKILL.md frontmatter description is required.');
-    if (description && description.length > 1024) fail('SKILL.md description must be <= 1024 characters.');
-    if (description && !description.includes("Don't use")) warn('Description should include negative triggers for discoverability.');
-  }
-
-  const lineCount = skillMd.split('\n').length;
-  if (lineCount > 500) fail(`SKILL.md must stay under 500 lines; found ${lineCount}.`);
-  if (!skillMd.includes('references/api-root.md')) fail('SKILL.md must point agents to references/api-root.md.');
-  if (!skillMd.includes('references/api-protocol.md')) fail('SKILL.md must point agents to references/api-protocol.md.');
-  if (!skillMd.includes('references/cli.md')) fail('SKILL.md must point agents to references/cli.md.');
-  if (!skillMd.includes('references/smoke-evaluation.md')) fail('SKILL.md must point evaluators to references/smoke-evaluation.md.');
-  if (!skillMd.includes('host/runtime') && !skillMd.includes('Host/runtime')) fail('SKILL.md must gate protocol usage to host/runtime tasks.');
-}
-
-const nestedReferenceFiles = existsSync(path.join(skillRoot, 'references'))
-  ? walk(path.join(skillRoot, 'references')).filter((file) =>
-      path.dirname(path.relative(path.join(skillRoot, 'references'), file)).includes(path.sep),
-    )
-  : [];
-for (const file of nestedReferenceFiles) fail(`References must be one level deep: ${skillRel(file)}`);
-
-if (existsSync(path.join(skillRoot, 'README.md')))
-  fail('Do not create README.md inside hb-sdk skill; keep human distribution docs outside the skill folder.');
-if (existsSync(path.join(skillRoot, 'CHANGELOG.md'))) fail('Do not create CHANGELOG.md inside hb-sdk skill.');
-if (existsSync(path.join(skillRoot, 'INSTALLATION_GUIDE.md'))) fail('Do not create INSTALLATION_GUIDE.md inside hb-sdk skill.');
-
-const textFiles = existsSync(skillRoot) ? walk(skillRoot).filter((file) => /\.(md|yaml|yml|json|txt)$/.test(file)) : [];
-
-const negativeMarkers = [
-  'do not',
-  "don't",
-  'does not',
-  'must not',
-  'never',
-  'no ',
-  'without',
-  'forbidden',
-  'refuse',
-  'block',
-  'fail',
-  'negative',
-  '不会',
-  '不应',
-  '不要',
-  '不能',
-  '不开放',
-  '无',
-  '禁止',
-];
-const positiveCredentialPattern =
-  /\b(read|extract|forward|store|persist|depend on|use|request|expose|get|parse|send)\b.*\b(token|cookie|credentials?|phone number|login state)\b/i;
-const unsupportedStoragePattern = /\b(removeStorage|clearStorage|getStorageInfo|getStorageV2|delete storage|clear storage)\b/i;
-const rawProtocolPattern = /\b(raw postMessage|construct bridge|bridge envelope|nonce handling|mutate bridge|sdk\.handshake)\b/i;
-const removedUserLoginPattern = /\b(?:hbSDK\.)?user\.login\s*\(/;
-const removedLocalIdentityPattern = /\b(?:hbSDK\.)?user\.getLocalIdentity\s*\(/;
-
-for (const file of textFiles) {
-  const relative = skillRel(file);
-  const content = read(file);
-  if (file.endsWith('.md')) validateLocalMarkdownLinks(file, content);
-  if (removedUserLoginPattern.test(content)) {
-    fail(
-      `Removed API guidance found in ${relative}: use auth.login() for network-enabled server authentication or user.getInfo() for network-disabled local identity instead of user.login().`,
-    );
-  }
-  if (removedLocalIdentityPattern.test(content)) {
-    fail(
-      `Removed API guidance found in ${relative}: use user.getInfo() and read userInfo.app_user_id for network-disabled local identity.`,
-    );
-  }
-
-  if (
-    new RegExp(`${HB_SDK_PACKAGE_NAME.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\/(?!(?:protocol|vite|miniapp-publish)\\b)[A-Za-z0-9_./-]+`).test(
-      content,
-    )
-  ) {
-    fail(
-      `Deep/internal hb-sdk import guidance found in ${relative}. Only @heybox/hb-sdk, @heybox/hb-sdk/protocol, @heybox/hb-sdk/vite, and @heybox/hb-sdk/miniapp-publish are allowed.`,
-    );
-  }
-
-  const lines = content.split('\n');
-  lines.forEach((line, index) => {
-    const lower = line.toLowerCase();
-    const isNegative = negativeMarkers.some((marker) => lower.includes(marker));
-    if (positiveCredentialPattern.test(line) && !isNegative) {
-      fail(`Unsafe positive credential guidance in ${relative}:${index + 1}: ${line.trim()}`);
-    }
-    if (unsupportedStoragePattern.test(line) && !isNegative) {
-      fail(`Unsupported storage capability guidance in ${relative}:${index + 1}: ${line.trim()}`);
-    }
-    if (rawProtocolPattern.test(line) && !isNegative && !/host\/runtime|runtime|protocol|parent-container|parent container|父容器/i.test(line)) {
-      fail(`Raw protocol guidance without host/runtime context in ${relative}:${index + 1}: ${line.trim()}`);
-    }
-  });
-}
-
-const recipesPath = path.join(skillRoot, 'references/recipes.md');
-if (existsSync(recipesPath)) {
-  const recipes = read(recipesPath);
-  if (/api-protocol\.md/.test(recipes) && !/host\/runtime-only|host\/runtime|runtime only/i.test(recipes)) {
-    fail('references/recipes.md references api-protocol.md without a nearby host/runtime-only warning.');
-  }
-}
-
-const protocolPath = path.join(skillRoot, 'references/api-protocol.md');
-if (existsSync(protocolPath)) {
-  const protocol = read(protocolPath);
-  if (!/Host\/runtime-only warning/i.test(protocol)) fail('references/api-protocol.md must include a Host/runtime-only warning section.');
-}
-
-const zipPath = path.join(packageRoot, 'hb-sdk.zip');
-if (existsSync(zipPath)) {
-  const size = statSync(zipPath).size;
-  if (size <= 0) fail('packages/hb-sdk/hb-sdk.zip exists but is empty.');
-}
-
-for (const warning of warnings) console.error(`warning: ${warning}`);
-if (errors.length > 0) {
-  for (const error of errors) console.error(`error: ${error}`);
-  process.exit(1);
-}
-
-console.log(JSON.stringify({ ok: true, skillRoot: rel(skillRoot), checkedFiles: textFiles.length, warnings: warnings.length }));