hive-lite 0.1.0

package/src/lib/scope.js

@@ -0,0 +1,168 @@
+const path = require('path');
+const { tryGit } = require('./git');
+const { matchesPattern } = require('./glob');
+
+function normalizePath(value) {
+  return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function patternFrom(value) {
+  if (!value) return '';
+  if (typeof value === 'string') return normalizePath(value.trim());
+  return normalizePath((value.pattern || value.path || '').trim());
+}
+
+function normalizePattern(value, defaults = {}) {
+  const pattern = patternFrom(value);
+  if (!pattern) return null;
+  if (typeof value === 'string') {
+    return {
+      pattern,
+      reason: defaults.reason || '',
+      requiresReview: defaults.requiresReview === true,
+      source: defaults.source || 'map',
+      matchCount: defaults.matchCount == null ? null : defaults.matchCount,
+    };
+  }
+  return {
+    pattern,
+    reason: value.reason || defaults.reason || '',
+    requiresReview: value.requires_review === true || value.requiresReview === true || defaults.requiresReview === true,
+    source: value.source || defaults.source || 'map',
+    matchCount: value.matchCount == null ? (defaults.matchCount == null ? null : defaults.matchCount) : value.matchCount,
+  };
+}
+
+function normalizePatternList(values, defaults = {}) {
+  return (values || []).map((value) => normalizePattern(value, defaults)).filter(Boolean);
+}
+
+function trackedFiles(root) {
+  const output = tryGit(['ls-files'], { cwd: root });
+  return output.split(/\r?\n/).filter(Boolean).map(normalizePath);
+}
+
+function matchCount(root, pattern) {
+  const files = trackedFiles(root);
+  if (files.length === 0) return null;
+  return files.filter((file) => matchesPattern(file, pattern)).length;
+}
+
+function looksLikeFile(pattern) {
+  if (pattern.includes('*')) return false;
+  const base = path.basename(pattern);
+  return /\.[A-Za-z0-9]+$/.test(base);
+}
+
+function isBroadPattern(root, pattern) {
+  const normalized = normalizePath(pattern);
+  const count = matchCount(root, normalized);
+  if (count != null && count > 30) return { broad: true, matchCount: count, reason: `matches ${count} tracked files` };
+  if (looksLikeFile(normalized)) return { broad: false, matchCount: count, reason: '' };
+  if (normalized.includes('**')) return { broad: true, matchCount: count, reason: 'recursive glob' };
+  if (normalized.endsWith('/*')) return { broad: true, matchCount: count, reason: 'directory wildcard' };
+  if (!normalized.includes('*') && !looksLikeFile(normalized)) {
+    if (count == null || count > 8) return { broad: true, matchCount: count, reason: count == null ? 'directory scope' : `matches ${count} tracked files` };
+  }
+  if (count != null && count > 8) return { broad: true, matchCount: count, reason: `matches ${count} tracked files` };
+  return { broad: false, matchCount: count, reason: '' };
+}
+
+function splitDirectAndBroad(root, values, defaults = {}) {
+  const direct = [];
+  const broad = [];
+  for (const value of values || []) {
+    const pattern = patternFrom(value);
+    if (!pattern) continue;
+    const classification = isBroadPattern(root, pattern);
+    const item = normalizePattern(value, {
+      ...defaults,
+      matchCount: classification.matchCount,
+    });
+    if (!item) continue;
+    if (classification.broad) {
+      broad.push({
+        ...item,
+        reason: item.reason || classification.reason || 'broad writable scope',
+        requiresReview: true,
+      });
+    } else {
+      direct.push(item.pattern);
+    }
+  }
+  return { direct, broad };
+}
+
+function normalizeAreaScope(root, area = {}) {
+  const configured = area.scope || {};
+  const readable = (configured.readable || area.readable_scope || []).map(patternFrom).filter(Boolean);
+  const forbidden = (configured.forbidden || area.do_not_touch || []).map(patternFrom).filter(Boolean);
+
+  const directValues = configured.writable_direct || [];
+  const conditionalValues = configured.writable_conditional || [];
+  const broadValues = configured.writable_broad_fallback || [];
+  const legacyWritable = !area.scope ? (area.writable_scope || []) : [];
+
+  const directSplit = splitDirectAndBroad(root, directValues, { source: 'writable_direct' });
+  const legacySplit = splitDirectAndBroad(root, legacyWritable, {
+    source: 'legacy_writable_scope',
+    reason: 'legacy writable_scope is broad; move this to scope.writable_broad_fallback or add writable_direct',
+  });
+
+  const writableDirect = [...directSplit.direct, ...legacySplit.direct];
+  const writableConditional = normalizePatternList(conditionalValues, {
+    source: 'writable_conditional',
+    requiresReview: true,
+  });
+  const writableBroadFallback = [
+    ...directSplit.broad,
+    ...normalizePatternList(broadValues, {
+      source: 'writable_broad_fallback',
+      requiresReview: true,
+    }).map((item) => {
+      const classification = isBroadPattern(root, item.pattern);
+      return {
+        ...item,
+        matchCount: classification.matchCount,
+        reason: item.reason || classification.reason || 'broad fallback scope',
+        requiresReview: true,
+      };
+    }),
+    ...legacySplit.broad,
+  ];
+
+  let quality = 'unknown';
+  if (writableBroadFallback.length > 0 && writableDirect.length === 0) quality = 'broad';
+  else if (writableConditional.length > 0 && writableDirect.length === 0) quality = 'conditional';
+  else if (writableDirect.length > 0 && (writableConditional.length > 0 || writableBroadFallback.length > 0)) quality = 'mixed';
+  else if (writableDirect.length > 0) quality = 'narrow';
+
+  return {
+    readable,
+    writableDirect,
+    writableConditional,
+    writableBroadFallback,
+    forbidden,
+    quality,
+  };
+}
+
+function itemPattern(item) {
+  return typeof item === 'string' ? item : item.pattern;
+}
+
+function patternDisplay(item) {
+  const pattern = itemPattern(item);
+  if (!pattern) return '';
+  if (typeof item === 'string') return pattern;
+  const count = item.matchCount == null ? '' : `, matches ${item.matchCount}`;
+  const reason = item.reason ? ` (${item.reason}${count})` : (count ? ` (${count.trim().replace(/^, /, '')})` : '');
+  return `${pattern}${reason}`;
+}
+
+module.exports = {
+  itemPattern,
+  normalizeAreaScope,
+  normalizePatternList,
+  patternDisplay,
+};

package/src/lib/skills.js

@@ -0,0 +1,349 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SKILL_NAMES = [
+  'hive-lite-start-prompt',
+  'hive-lite-finish',
+  'hive-lite-map-maintainer',
+];
+
+const AGENTS = {
+  codex: {
+    label: 'Codex global user skills',
+    path: '~/.codex/skills',
+    scope: 'global_user',
+    note: 'Codex installs use the global user skills directory, not repo-local .codex/skills. Use --path .codex/skills only when you intentionally want a custom repo-local copy.',
+  },
+  claude: {
+    label: 'Claude global user skills',
+    path: '~/.claude/skills',
+    scope: 'global_user',
+    note: 'Claude installs use the global user skills directory.',
+  },
+  gemini: {
+    label: 'Gemini global user skills',
+    path: '~/.gemini/skills',
+    scope: 'global_user',
+    note: 'Gemini installs use the global user skills directory, not repo-local .gemini/skills. Use --path .gemini/skills only when you intentionally want a custom repo-local copy.',
+  },
+};
+
+function packageRoot() {
+  return path.resolve(__dirname, '..', '..');
+}
+
+function sourceSkillsDir() {
+  return path.join(packageRoot(), 'docs', 'skills');
+}
+
+function expandPath(value, cwd) {
+  const text = String(value || '');
+  if (text === '~') return os.homedir();
+  if (text.startsWith('~/')) return path.join(os.homedir(), text.slice(2));
+  if (path.isAbsolute(text)) return text;
+  return path.resolve(cwd, text);
+}
+
+function relPath(root, file) {
+  return path.relative(root, file).replace(/\\/g, '/');
+}
+
+function sourceSkillPath(name) {
+  return path.join(sourceSkillsDir(), name);
+}
+
+function listFiles(dir, base = dir) {
+  if (!fs.existsSync(dir)) return [];
+  const result = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === '.DS_Store') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) result.push(...listFiles(full, base));
+    else if (entry.isFile()) result.push(relPath(base, full));
+  }
+  return result.sort();
+}
+
+function dirDigest(dir) {
+  if (!fs.existsSync(dir)) return null;
+  const hash = crypto.createHash('sha256');
+  for (const file of listFiles(dir)) {
+    hash.update(file);
+    hash.update('\0');
+    hash.update(fs.readFileSync(path.join(dir, file)));
+    hash.update('\0');
+  }
+  return `sha256:${hash.digest('hex')}`;
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name === '.DS_Store') continue;
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(from, to);
+    } else if (entry.isFile()) {
+      fs.mkdirSync(path.dirname(to), { recursive: true });
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+function validateSources() {
+  const missing = SKILL_NAMES.filter((name) => !fs.existsSync(path.join(sourceSkillsDir(), name, 'SKILL.md')));
+  if (missing.length > 0) throw new Error(`missing bundled Hive Lite skill sources: ${missing.join(', ')}`);
+}
+
+function targetSpecs(cwd, options = {}, command = 'doctor') {
+  if (options.path && options.path !== true) {
+    return [{
+      agent: 'custom',
+      label: 'Custom skills path',
+      root: expandPath(options.path, cwd),
+      configuredPath: options.path,
+      scope: 'custom',
+      note: 'Custom --path targets are copied exactly where requested.',
+    }];
+  }
+
+  let agents = [];
+  if (options.agent && options.agent !== true) {
+    agents = String(options.agent).split(',').map((item) => item.trim()).filter(Boolean);
+  } else if (options.all) {
+    agents = ['codex', 'claude', 'gemini'];
+  } else if (command === 'doctor') {
+    agents = ['codex', 'claude', 'gemini'];
+  }
+
+  if (agents.includes('all')) agents = ['codex', 'claude', 'gemini'];
+
+  if (agents.length === 0) {
+    throw new Error(`${command} requires --agent codex|claude|gemini|all or --path <skills-dir>`);
+  }
+
+  return agents.map((agent) => {
+    const config = AGENTS[agent];
+    if (!config) throw new Error(`unknown skill agent: ${agent}`);
+    return {
+      agent,
+      label: config.label,
+      root: expandPath(config.path, cwd),
+      configuredPath: config.path,
+      scope: config.scope,
+      note: config.note,
+    };
+  });
+}
+
+function inspectTarget(spec) {
+  return {
+    agent: spec.agent,
+    label: spec.label,
+    path: spec.root,
+    configuredPath: spec.configuredPath,
+    scope: spec.scope || 'unknown',
+    note: spec.note || '',
+    exists: fs.existsSync(spec.root),
+    skills: SKILL_NAMES.map((name) => {
+      const source = sourceSkillPath(name);
+      const target = path.join(spec.root, name);
+      const sourceDigest = dirDigest(source);
+      const targetDigest = dirDigest(target);
+      let status = 'missing';
+      if (targetDigest && targetDigest === sourceDigest) status = 'current';
+      else if (targetDigest) status = 'stale';
+      return {
+        name,
+        status,
+        sourcePath: source,
+        targetPath: target,
+        sourceDigest,
+        targetDigest,
+      };
+    }),
+  };
+}
+
+function skillsDoctor(cwd, options = {}) {
+  validateSources();
+  const specs = targetSpecs(cwd, options, 'doctor');
+  const targets = specs.map(inspectTarget);
+  return {
+    version: 1,
+    command: 'skills doctor',
+    generatedAt: new Date().toISOString(),
+    sourceDir: sourceSkillsDir(),
+    targetSelection: targetSelection(options, 'doctor'),
+    targets,
+    summary: summarizeTargets(targets),
+  };
+}
+
+function targetSelection(options = {}, command = 'doctor') {
+  if (options.path && options.path !== true) {
+    return {
+      mode: 'custom_path',
+      detectsRunningAgentCli: false,
+      note: 'Hive Lite checks the requested skills directory. It does not detect which agent CLI is running.',
+    };
+  }
+  if (options.agent && options.agent !== true) {
+    return {
+      mode: 'explicit_agent',
+      detectsRunningAgentCli: false,
+      note: 'Hive Lite checks the explicitly requested target path(s). It does not detect which agent CLI is running.',
+    };
+  }
+  if (options.all) {
+    return {
+      mode: 'all_known_targets',
+      detectsRunningAgentCli: false,
+      note: 'Hive Lite checks all known target paths. It does not detect which agent CLI is running.',
+    };
+  }
+  return {
+    mode: command === 'doctor' ? 'default_known_targets' : 'none',
+    detectsRunningAgentCli: false,
+    note: command === 'doctor'
+      ? 'By default, skills doctor checks all known target paths. It does not detect installed or currently running agent CLIs.'
+      : 'Hive Lite does not detect which agent CLI is running.',
+  };
+}
+
+function installCommandForOptions(options = {}) {
+  if (options.path && options.path !== true) return `hive-lite skills install --path ${options.path}`;
+  if (options.agent && options.agent !== true) return `hive-lite skills install --agent ${options.agent}`;
+  if (options.all) return 'hive-lite skills install --agent all';
+  return 'hive-lite skills install --agent <codex|claude|gemini>';
+}
+
+function skillPreflight(cwd, skillName, options = {}) {
+  if (!skillName) return null;
+  if (!options.agent && !options.path && !options.all) return null;
+  validateSources();
+  const specs = targetSpecs(cwd, options, 'doctor');
+  const targets = specs.map((spec) => {
+    const target = inspectTarget(spec);
+    const skill = target.skills.find((item) => item.name === skillName);
+    return {
+      agent: target.agent,
+      label: target.label,
+      path: target.path,
+      configuredPath: target.configuredPath,
+      scope: target.scope,
+      note: target.note,
+      exists: target.exists,
+      status: skill ? skill.status : 'missing',
+      targetPath: skill ? skill.targetPath : null,
+    };
+  });
+  return {
+    requiredSkill: skillName,
+    targetSelection: targetSelection(options, 'doctor'),
+    ready: targets.length > 0 && targets.every((target) => target.status === 'current'),
+    installCommand: installCommandForOptions(options),
+    targets,
+  };
+}
+
+function summarizeTargets(targets) {
+  const counts = { current: 0, stale: 0, missing: 0 };
+  for (const target of targets) {
+    for (const skill of target.skills) counts[skill.status] += 1;
+  }
+  return counts;
+}
+
+function installIntoTarget(spec, options) {
+  const before = inspectTarget(spec);
+  const dryRun = Boolean(options.dryRun);
+  const overwrite = Boolean(options.overwrite);
+  const installed = [];
+  const updated = [];
+  const unchanged = [];
+  const skipped = [];
+
+  for (const skill of before.skills) {
+    const source = sourceSkillPath(skill.name);
+    const target = path.join(spec.root, skill.name);
+    if (skill.status === 'current') {
+      unchanged.push(skill.name);
+      continue;
+    }
+    if (skill.status === 'stale' && !overwrite) {
+      skipped.push({
+        name: skill.name,
+        reason: 'target exists but differs; use skills sync or --force to overwrite',
+      });
+      continue;
+    }
+    if (!dryRun) {
+      if (overwrite && fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true });
+      copyDir(source, target);
+    }
+    if (skill.status === 'missing') installed.push(skill.name);
+    else updated.push(skill.name);
+  }
+
+  const after = dryRun ? before : inspectTarget(spec);
+  return {
+    agent: spec.agent,
+    label: spec.label,
+    path: spec.root,
+    configuredPath: spec.configuredPath,
+    scope: spec.scope || 'unknown',
+    note: spec.note || '',
+    dryRun,
+    installed,
+    updated,
+    unchanged,
+    skipped,
+    before,
+    after,
+  };
+}
+
+function installSkills(cwd, options = {}) {
+  validateSources();
+  const specs = targetSpecs(cwd, options, 'install');
+  const results = specs.map((spec) => installIntoTarget(spec, {
+    dryRun: options.dryRun,
+    overwrite: options.force,
+  }));
+  return {
+    version: 1,
+    command: 'skills install',
+    generatedAt: new Date().toISOString(),
+    sourceDir: sourceSkillsDir(),
+    results,
+  };
+}
+
+function syncSkills(cwd, options = {}) {
+  validateSources();
+  const specs = targetSpecs(cwd, options, 'sync');
+  const results = specs.map((spec) => installIntoTarget(spec, {
+    dryRun: options.dryRun,
+    overwrite: true,
+  }));
+  return {
+    version: 1,
+    command: 'skills sync',
+    generatedAt: new Date().toISOString(),
+    sourceDir: sourceSkillsDir(),
+    results,
+  };
+}
+
+module.exports = {
+  AGENTS,
+  SKILL_NAMES,
+  installSkills,
+  skillPreflight,
+  skillsDoctor,
+  syncSkills,
+};