@yottameta/yotta-skills 0.7.2 → 0.19.0

package/lib/hook-adapter.js

@@ -0,0 +1,385 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const EVENTS = [
+  'before_start',
+  'before_tool',
+  'before_install',
+  'before_publish',
+  'after_milestone',
+  'before_send',
+];
+
+const CAPABILITY_LEVELS = [
+  'native-block',
+  'native-audit',
+  'wrapper-only',
+  'unsupported',
+];
+
+const EVIDENCE_KINDS = [
+  'tool_call_id',
+  'hook_event_id',
+  'host_transcript',
+  'file_path',
+  'exit_code',
+  'audit_log',
+];
+
+const FALLBACKS = ['wrapper', 'advisory', 'explicit-unverified'];
+
+const CODEX_CAPABILITIES = {
+  before_start: 'native-audit',
+  before_tool: 'native-audit',
+  before_install: 'wrapper-only',
+  before_publish: 'wrapper-only',
+  after_milestone: 'native-audit',
+  before_send: 'unsupported',
+};
+
+function unsupportedCapabilities() {
+  return EVENTS.reduce((out, event) => {
+    out[event] = 'unsupported';
+    return out;
+  }, {});
+}
+
+function capabilitiesForHost(host) {
+  if (host === 'codex') return { ...CODEX_CAPABILITIES };
+  return unsupportedCapabilities();
+}
+
+function validateHookRequirements(manifest) {
+  const errors = [];
+  const requirements = manifest && Array.isArray(manifest.hooks) ? manifest.hooks : [];
+  requirements.forEach((requirement, index) => {
+    const prefix = 'hooks[' + index + ']';
+    if (!requirement || typeof requirement !== 'object' || Array.isArray(requirement)) {
+      errors.push(prefix + ': 必须是对象');
+      return;
+    }
+    if (!EVENTS.includes(requirement.event)) {
+      errors.push(prefix + ': event 非法');
+    }
+    if (!['block', 'warn'].includes(requirement.on_fail)) {
+      errors.push(prefix + ': on_fail 非法');
+    }
+    if (!requirement.require_tool && !requirement.require_action) {
+      errors.push(prefix + ': 必须声明 require_tool 或 require_action');
+    }
+    if (!Array.isArray(requirement.evidence) || requirement.evidence.length === 0) {
+      errors.push(prefix + ': evidence 不能为空');
+    } else if (requirement.evidence.some((kind) => !EVIDENCE_KINDS.includes(kind))) {
+      errors.push(prefix + ': evidence 含不支持的来源');
+    }
+    if (requirement.fallback !== undefined && !FALLBACKS.includes(requirement.fallback)) {
+      errors.push(prefix + ': fallback 非法');
+    }
+  });
+  return { errors, requirements };
+}
+
+function actionOf(requirement, index) {
+  return requirement.require_tool || requirement.require_action || ('hook-' + index);
+}
+
+function checkFor(context, requirement) {
+  const key = requirement.require_tool || requirement.require_action;
+  return context && context.checks && context.checks[key] ? context.checks[key] : null;
+}
+
+function evidenceFor(requirement, context, check) {
+  const out = {};
+  for (const kind of requirement.evidence || []) {
+    if (check && check.evidence && check.evidence[kind] !== undefined) out[kind] = check.evidence[kind];
+    else if (context && context.evidence && context.evidence[kind] !== undefined) out[kind] = context.evidence[kind];
+  }
+  return out;
+}
+
+function evaluateOne(requirement, index, event, capability, context, skill) {
+  const action = actionOf(requirement, index);
+  const check = checkFor(context, requirement);
+  const evidence = evidenceFor(requirement, context, check);
+  const hasEvidence = Object.keys(evidence).length > 0;
+  const passed = !!check && check.ok === true;
+  const failed = !!check && check.ok === false;
+  const missing = !check;
+  let decision = 'allow';
+  let reason = '检查通过';
+  let correction = false;
+
+  if (passed) {
+    const canVerify = capability === 'native-block'
+      || capability === 'native-audit'
+      || (capability === 'wrapper-only' && context && context.wrapperRegistered === true);
+    if (!canVerify) {
+      decision = 'unverified';
+      reason = hasEvidence ? '宿主能力不足，不能声明为强制' : '缺少可验证证据';
+    } else if (!hasEvidence) {
+      decision = 'unverified';
+      reason = '缺少声明要求的可验证证据';
+    }
+  } else if (failed || missing) {
+    if (requirement.on_fail === 'warn') {
+      decision = 'warn';
+      reason = '检查未通过，按声明降级为警告';
+    } else if (capability === 'native-block') {
+      decision = 'block';
+      reason = '检查未通过，宿主支持动作前阻断';
+    } else if (capability === 'wrapper-only') {
+      if (context && context.wrapperRegistered === true) {
+        decision = 'block';
+        reason = '检查未通过，wrapper 路径可阻断';
+      } else {
+        decision = 'unverified';
+        reason = 'wrapper 未注册，无法保证拦截';
+      }
+    } else if (capability === 'native-audit') {
+      decision = 'unverified';
+      correction = true;
+      reason = '动作已发生，只能审计并触发一次纠偏';
+    } else {
+      decision = 'unverified';
+      reason = '宿主不支持该事件，按 explicit-unverified 降级';
+    }
+  }
+
+  return {
+    event,
+    skill: skill || null,
+    action,
+    capability,
+    decision,
+    passed,
+    failed,
+    missing,
+    correction,
+    evidence,
+    reason,
+    requirement,
+  };
+}
+
+function evaluateHook(input) {
+  const opts = input || {};
+  const event = opts.event;
+  const context = opts.context || {};
+  const manifest = opts.manifest || {};
+  const capabilities = opts.capabilities || capabilitiesForHost(opts.host || 'generic');
+  if (!EVENTS.includes(event)) {
+    return {
+      decision: 'block',
+      verified: false,
+      correction: false,
+      results: [],
+      evidence: [],
+      user_message: '阻断：未知 hook 事件 ' + event,
+      errors: ['未知 hook 事件: ' + event],
+    };
+  }
+
+  const validation = validateHookRequirements(manifest);
+  if (validation.errors.length > 0) {
+    return {
+      decision: 'block',
+      verified: false,
+      correction: false,
+      results: [],
+      evidence: [],
+      user_message: '阻断：manifest hook 声明非法',
+      errors: validation.errors,
+    };
+  }
+
+  const requirements = validation.requirements.filter((requirement) => requirement.event === event);
+  const results = requirements.map((requirement, index) => evaluateOne(
+    requirement,
+    index,
+    event,
+    capabilities[event] || 'unsupported',
+    context,
+    manifest.slug,
+  ));
+  const decision = results.some((result) => result.decision === 'block')
+    ? 'block'
+    : results.some((result) => result.decision === 'warn')
+      ? 'warn'
+      : results.some((result) => result.decision === 'unverified')
+        ? 'unverified'
+        : 'allow';
+  const evidence = results.map((result) => ({
+    event: result.event,
+    skill: result.skill,
+    action: result.action,
+    result: result.decision,
+    capability: result.capability,
+    evidence: result.evidence,
+    reason: result.reason,
+  }));
+  const correction = results.some((result) => result.correction);
+  const verified = decision === 'allow' && results.every((result) => result.decision === 'allow');
+  let userMessage = '已通过';
+  if (decision === 'block') userMessage = '阻断：' + results.filter((result) => result.decision === 'block').map((result) => result.reason).join('；');
+  else if (decision === 'warn') userMessage = '警告：' + results.filter((result) => result.decision === 'warn').map((result) => result.reason).join('；');
+  else if (decision === 'unverified') userMessage = 'explicit-unverified：' + results.filter((result) => result.decision === 'unverified').map((result) => result.reason).join('；');
+
+  return {
+    decision,
+    verified,
+    correction,
+    results,
+    evidence,
+    user_message: userMessage,
+    errors: [],
+  };
+}
+
+function hookLogPath(homeDir) {
+  return path.join(homeDir || os.homedir(), '.yottaskills', 'hook-log.jsonl');
+}
+
+function bindingsPath(homeDir) {
+  return path.join(homeDir || os.homedir(), '.yottaskills', 'hook-bindings.json');
+}
+
+function appendHookEvidence(entry, options) {
+  const file = hookLogPath(options && options.homeDir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const record = {
+    ...entry,
+    timestamp: entry.timestamp || new Date().toISOString(),
+  };
+  fs.appendFileSync(file, JSON.stringify(record) + '\n', 'utf8');
+  return file;
+}
+
+function emptyBindings() {
+  return { version: 1, bindings: {} };
+}
+
+function readBindings(homeDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(bindingsPath(homeDir), 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !parsed.bindings) return emptyBindings();
+    return { version: 1, bindings: { ...parsed.bindings } };
+  } catch (_) {
+    return emptyBindings();
+  }
+}
+
+function writeBindings(homeDir, value) {
+  const file = bindingsPath(homeDir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp-' + process.pid + '-' + Date.now();
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', 'utf8');
+  try {
+    fs.renameSync(tmp, file);
+  } catch (_) {
+    fs.rmSync(file, { force: true });
+    fs.renameSync(tmp, file);
+  }
+  return file;
+}
+
+function bindingId(host, skill, event, action) {
+  return crypto.createHash('sha256').update([host, skill, event, action].join('|')).digest('hex').slice(0, 24);
+}
+
+function bindHookRequirements(input) {
+  const opts = input || {};
+  const manifest = opts.manifest || {};
+  const validation = validateHookRequirements(manifest);
+  if (validation.errors.length > 0) {
+    const error = new Error(validation.errors.join('; '));
+    error.errors = validation.errors;
+    throw error;
+  }
+  const capabilities = capabilitiesForHost(opts.host || 'generic');
+  const selected = opts.event
+    ? validation.requirements.filter((requirement) => requirement.event === opts.event)
+    : validation.requirements;
+  const registry = readBindings(opts.homeDir);
+  const records = selected.map((requirement, index) => {
+    const action = actionOf(requirement, index);
+    const id = bindingId(opts.host || 'generic', manifest.slug, requirement.event, action);
+    const previous = registry.bindings[id];
+    const record = {
+      id,
+      host: opts.host || 'generic',
+      skill: manifest.slug,
+      event: requirement.event,
+      action,
+      on_fail: requirement.on_fail,
+      fallback: requirement.fallback || 'explicit-unverified',
+      capability: capabilities[requirement.event] || 'unsupported',
+      created_at: previous ? previous.created_at : new Date().toISOString(),
+    };
+    registry.bindings[id] = record;
+    return record;
+  });
+  writeBindings(opts.homeDir, registry);
+  return records;
+}
+
+function listHookBindings(homeDir) {
+  return Object.values(readBindings(homeDir).bindings)
+    .sort((a, b) => String(a.created_at).localeCompare(String(b.created_at)) || a.id.localeCompare(b.id));
+}
+
+function unbindHookBinding(id, options) {
+  const registry = readBindings(options && options.homeDir);
+  if (!registry.bindings[id]) return false;
+  delete registry.bindings[id];
+  writeBindings(options && options.homeDir, registry);
+  return true;
+}
+
+function createHookAdapter(options) {
+  const opts = options || {};
+  const host = opts.host || 'generic';
+  const capabilities = capabilitiesForHost(host);
+  return {
+    host,
+    capabilities: () => ({ ...capabilities }),
+    validate: (manifest) => validateHookRequirements(manifest),
+    evaluate: (event, manifest, context) => evaluateHook({
+      host,
+      event,
+      manifest,
+      context,
+      capabilities,
+    }),
+    bind: (manifest, event) => bindHookRequirements({
+      host,
+      homeDir: opts.homeDir,
+      manifest,
+      event,
+    }),
+    unbind: (id) => unbindHookBinding(id, { homeDir: opts.homeDir }),
+    listBindings: () => listHookBindings(opts.homeDir),
+  };
+}
+
+module.exports = {
+  EVENTS,
+  CAPABILITY_LEVELS,
+  EVIDENCE_KINDS,
+  FALLBACKS,
+  CODEX_CAPABILITIES,
+  appendHookEvidence,
+  bindHookRequirements,
+  bindingId,
+  bindingsPath,
+  capabilitiesForHost,
+  createHookAdapter,
+  evaluateHook,
+  hookLogPath,
+  listHookBindings,
+  unbindHookBinding,
+  validateHookRequirements,
+};

package/lib/install-evidence.js

@@ -0,0 +1,18 @@
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function evidencePath(options) {
+  const home = (options && options.homeDir) || os.homedir();
+  return path.join(home, '.yottaskills', 'install-log.jsonl');
+}
+
+function appendEvidence(entry, options) {
+  const file = evidencePath(options);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
+  return file;
+}
+
+module.exports = { evidencePath, appendEvidence };

package/lib/install-health.js

@@ -0,0 +1,151 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const manifestLib = require('./manifest');
+const scanLib = require('./skills-scan');
+
+function addCheck(checks, id, ok, message, severity, hint) {
+  checks.push({
+    id,
+    ok: !!ok,
+    severity: severity || (ok ? 'info' : 'error'),
+    message,
+    hint: hint || null,
+  });
+}
+
+function readManifest(target, slug) {
+  const file = path.join(target, manifestLib.MANIFEST_FILE);
+  if (!fs.existsSync(file)) return { value: null, error: null };
+  try {
+    return { value: JSON.parse(fs.readFileSync(file, 'utf8')), error: null };
+  } catch (error) {
+    return { value: null, error: '无法解析 skill-manifest.json: ' + error.message };
+  }
+}
+
+function checkInstalledSkill(context) {
+  const ctx = context || {};
+  const slug = String(ctx.slug || '');
+  const target = ctx.target ? path.resolve(ctx.target) : '';
+  const checks = [];
+  const errors = [];
+  const warnings = [];
+  const fixes = [];
+  let version = null;
+
+  if (!slug) {
+    addCheck(checks, 'slug', false, '缺少技能 slug');
+    errors.push('缺少技能 slug');
+  }
+  if (!target || !fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+    addCheck(checks, 'target', false, '技能目录不存在' + (target ? ': ' + target : ''));
+    errors.push('技能目录不存在' + (target ? ': ' + target : ''));
+    return { ok: false, slug, version, checks, errors, warnings, fixes };
+  }
+  addCheck(checks, 'target', true, '技能目录存在');
+
+  const skillFile = path.join(target, 'SKILL.md');
+  let text = null;
+  try {
+    text = fs.readFileSync(skillFile, 'utf8');
+    addCheck(checks, 'skill_file', true, 'SKILL.md 可读');
+  } catch (error) {
+    addCheck(checks, 'skill_file', false, 'SKILL.md 不可读: ' + error.message);
+    errors.push('SKILL.md 不可读: ' + error.message);
+  }
+
+  let frontmatter = null;
+  if (text !== null) {
+    frontmatter = scanLib.parseFrontmatter(text);
+    if (!frontmatter) {
+      addCheck(checks, 'frontmatter', false, 'SKILL.md 缺少有效 frontmatter');
+      errors.push('SKILL.md 缺少有效 frontmatter');
+    } else {
+      addCheck(checks, 'frontmatter', true, 'SKILL.md frontmatter 有效');
+      if (frontmatter.name !== slug) {
+        addCheck(checks, 'slug_identity', false, 'SKILL.md name 与目标 slug 不一致');
+        errors.push('SKILL.md name 与目标 slug 不一致');
+      } else {
+        addCheck(checks, 'slug_identity', true, 'SKILL.md slug 一致');
+      }
+      version = frontmatter.version ? String(frontmatter.version).trim() : null;
+      if (!version || !/^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+        addCheck(checks, 'version_format', false, 'SKILL.md 版本号非法');
+        errors.push('SKILL.md 版本号非法');
+      } else {
+        addCheck(checks, 'version_format', true, 'SKILL.md 版本号有效');
+      }
+    }
+  }
+
+  if (ctx.expectedVersion && version && version !== ctx.expectedVersion) {
+    addCheck(checks, 'version_match', false, '版本不一致：已安装 v' + version + '，期望 v' + ctx.expectedVersion);
+    errors.push('版本不一致：已安装 v' + version + '，期望 v' + ctx.expectedVersion);
+  } else if (ctx.expectedVersion && version) {
+    addCheck(checks, 'version_match', true, '版本与期望一致');
+  }
+
+  const loadedManifest = readManifest(target, slug);
+  if (loadedManifest.error) {
+    addCheck(checks, 'manifest', false, loadedManifest.error);
+    errors.push(loadedManifest.error);
+  } else if (loadedManifest.value) {
+    if (loadedManifest.value.trust !== 'yottameta') {
+      addCheck(checks, 'manifest_trust', false, 'manifest trust 必须为 yottameta');
+      errors.push('manifest trust 必须为 yottameta');
+    } else {
+      addCheck(checks, 'manifest_trust', true, 'manifest trust 为 yottameta');
+    }
+    const validation = manifestLib.validateManifest(loadedManifest.value, {
+      skill: {
+        slug,
+        pkg: ctx.expectedPackage || loadedManifest.value.package,
+        version: version || loadedManifest.value.version,
+      },
+      pkgDir: target,
+      requirePackageJson: false,
+    });
+    if (!validation.ok) {
+      addCheck(checks, 'manifest', false, 'manifest 校验失败: ' + validation.errors.join('; '));
+      errors.push.apply(errors, validation.errors);
+    } else {
+      addCheck(checks, 'manifest', true, 'manifest 校验通过');
+    }
+  } else {
+    addCheck(checks, 'manifest', true, '未提供 skill-manifest.json，使用家族默认契约');
+  }
+
+  if (ctx.registry) {
+    const record = ctx.registry.skills && ctx.registry.skills[slug];
+    if (!record || record.status === 'gone') {
+      addCheck(checks, 'registry', false, '注册表未记录当前技能', 'warning');
+      warnings.push('注册表未记录当前技能');
+      fixes.push('运行 yotta-skills --reindex 重扫注册表');
+    } else if (version && record.version && record.version !== version) {
+      addCheck(
+        checks,
+        'registry',
+        false,
+        '注册表版本 v' + record.version + ' 与已安装 v' + version + ' 不一致',
+        'warning',
+      );
+      warnings.push('注册表版本 v' + record.version + ' 与已安装 v' + version + ' 不一致');
+      fixes.push('运行 yotta-skills --reindex 重扫注册表');
+    } else {
+      addCheck(checks, 'registry', true, '注册表记录一致');
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    slug,
+    version,
+    checks,
+    errors,
+    warnings,
+    fixes: Array.from(new Set(fixes)),
+  };
+}
+
+module.exports = { checkInstalledSkill };

package/lib/install-lifecycle.js

@@ -0,0 +1,149 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const manifestLib = require('./manifest');
+
+const PHASES = ['setup', 'doctor', 'rollback'];
+
+function parseJsonResult(stdout) {
+  const text = String(stdout || '').trim();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch (_) {
+    const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (!lines[i].startsWith('{')) continue;
+      try {
+        return JSON.parse(lines[i]);
+      } catch (_) {
+        // Keep looking for the structured result line.
+      }
+    }
+  }
+  return null;
+}
+
+function runLifecycleScript(scriptPath, args, options) {
+  const opts = options || {};
+  if (!scriptPath || !fs.existsSync(scriptPath) || !fs.statSync(scriptPath).isFile()) {
+    return {
+      ok: false,
+      skipped: false,
+      result: null,
+      error: '生命周期脚本不存在: ' + (scriptPath || '未提供'),
+      stdout: '',
+      stderr: '',
+      exitCode: null,
+    };
+  }
+  if (!/\.(?:js|cjs)$/i.test(scriptPath)) {
+    return {
+      ok: false,
+      skipped: false,
+      result: null,
+      error: '生命周期脚本必须为 Node.js .js/.cjs 文件',
+      stdout: '',
+      stderr: '',
+      exitCode: null,
+    };
+  }
+
+  const spawn = opts.spawnSync || spawnSync;
+  const argv = [scriptPath].concat(Array.isArray(args) ? args : []).concat(['--json']);
+  let proc;
+  try {
+    proc = spawn(process.execPath, argv, {
+      cwd: opts.cwd || path.dirname(scriptPath),
+      encoding: 'utf8',
+      timeout: opts.timeout || 30000,
+      maxBuffer: opts.maxBuffer || 4 * 1024 * 1024,
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      skipped: false,
+      result: null,
+      error: error.message,
+      stdout: '',
+      stderr: '',
+      exitCode: null,
+    };
+  }
+
+  const stdout = proc.stdout || '';
+  const stderr = proc.stderr || '';
+  const parsed = parseJsonResult(stdout);
+  const exitCode = proc.status;
+  if (proc.error) {
+    return { ok: false, skipped: false, result: parsed, error: proc.error.message, stdout, stderr, exitCode };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {
+      ok: false,
+      skipped: false,
+      result: null,
+      error: '生命周期脚本未返回合法 JSON' + (stderr ? '：' + stderr.trim() : ''),
+      stdout,
+      stderr,
+      exitCode,
+    };
+  }
+  if (exitCode !== 0) {
+    return {
+      ok: false,
+      skipped: false,
+      result: parsed,
+      error: parsed.error || stderr.trim() || ('生命周期脚本退出码 ' + exitCode),
+      stdout,
+      stderr,
+      exitCode,
+    };
+  }
+  if (parsed.ok === false) {
+    return {
+      ok: false,
+      skipped: false,
+      result: parsed,
+      error: parsed.error || '生命周期脚本返回失败',
+      stdout,
+      stderr,
+      exitCode,
+    };
+  }
+  return { ok: true, skipped: false, result: parsed, error: null, stdout, stderr, exitCode };
+}
+
+function runPhase(packageDir, manifest, phase, context) {
+  if (!PHASES.includes(phase)) {
+    return { ok: false, skipped: false, result: null, error: '未知生命周期阶段: ' + phase };
+  }
+  const ctx = context || {};
+  const install = manifest && manifest.install ? manifest.install : {};
+  const rel = install[phase];
+  if (!rel) {
+    return { ok: true, skipped: true, result: null, error: null };
+  }
+  if (!manifestLib.isSafeRelativePath(rel)) {
+    return { ok: false, skipped: false, result: null, error: '生命周期脚本路径不安全: ' + rel };
+  }
+  const root = path.resolve(packageDir);
+  const scriptPath = path.resolve(root, rel);
+  const relative = path.relative(root, scriptPath);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    return { ok: false, skipped: false, result: null, error: '生命周期脚本越出包目录: ' + rel };
+  }
+
+  const args = [];
+  if (ctx.skillDir) args.push('--skill-dir', ctx.skillDir);
+  if (ctx.packageDir || packageDir) args.push('--package-dir', ctx.packageDir || packageDir);
+  if (ctx.dest) args.push('--dest', ctx.dest);
+  if (ctx.snapshot) args.push('--snapshot', ctx.snapshot);
+  return runLifecycleScript(scriptPath, args, {
+    ...ctx.options,
+    cwd: (ctx.options && ctx.options.cwd) || root,
+  });
+}
+
+module.exports = { PHASES, parseJsonResult, runLifecycleScript, runPhase };