hive-lite 0.1.0

package/src/lib/next.js

@@ -0,0 +1,341 @@
+const { allDeltas, latestChangeId, loadChange } = require('./change');
+const { repoRoot } = require('./git');
+const { evaluateMapHealth } = require('./health');
+const { skillPreflight } = require('./skills');
+const { evaluateWorkspaceStatus } = require('./status');
+
+function pendingDeltas(root) {
+  try {
+    return allDeltas(root).filter((delta) => delta.status !== 'applied' && delta.status !== 'rejected');
+  } catch {
+    return [];
+  }
+}
+
+function latestChangeSummary(root) {
+  const id = latestChangeId(root);
+  if (!id) return null;
+  try {
+    const change = loadChange(root, id);
+    return {
+      id,
+      verdict: change.evidencePolicy ? change.evidencePolicy.verdict : change.risk ? change.risk.verdict : null,
+      validationStatus: change.validation ? change.validation.status : null,
+      accepted: Boolean(change.humanDecision && change.humanDecision.status === 'accepted'),
+      committed: Boolean(change.humanDecision && change.humanDecision.commit),
+      decisionMode: change.humanDecision ? change.humanDecision.mode : null,
+      contextId: change.context ? change.context.id : null,
+      originSplit: change.originSplit || null,
+    };
+  } catch {
+    return {
+      id,
+      verdict: null,
+      validationStatus: null,
+      accepted: false,
+      committed: false,
+      decisionMode: null,
+      contextId: null,
+      originSplit: null,
+    };
+  }
+}
+
+function mapHealthSummary(root) {
+  try {
+    const health = evaluateMapHealth(root, {});
+    return {
+      status: health.status,
+      critical: health.summary.critical,
+      warnings: health.summary.warnings,
+      info: health.summary.info,
+      areasChecked: health.summary.areasChecked,
+      topFindings: health.findings.slice(0, 5).map((finding) => ({
+        severity: finding.severity,
+        code: finding.code,
+        areaId: finding.areaId,
+        message: finding.message,
+      })),
+    };
+  } catch (error) {
+    return {
+      status: 'unknown',
+      critical: 0,
+      warnings: 0,
+      info: 0,
+      areasChecked: 0,
+      topFindings: [{
+        severity: 'warning',
+        code: 'MAP_HEALTH_UNAVAILABLE',
+        areaId: null,
+        message: error.message,
+      }],
+    };
+  }
+}
+
+function action(data) {
+  return {
+    kind: data.kind,
+    label: data.label,
+    command: data.command || null,
+    prompt: data.prompt || null,
+    requiresHuman: data.requiresHuman !== false,
+    enabled: data.enabled !== false,
+    disabledReason: data.disabledReason || null,
+    explanation: data.explanation || '',
+  };
+}
+
+function startPrompt() {
+  return [
+    '$hive-lite-start-prompt',
+    '<describe the requirement you want to start>',
+  ].join('\n');
+}
+
+function finishPrompt(changeId) {
+  return [
+    '$hive-lite-finish',
+    changeId ? `Close Hive Lite change ${changeId}.` : 'Close the current Hive Lite change.',
+  ].join('\n');
+}
+
+function mapMaintainerPrompt(mode) {
+  if (mode === 'bootstrap') {
+    return [
+      '$hive-lite-map-maintainer',
+      '这个项目第一次使用 Hive Lite，请初始化并建立第一版 3-8 个高价值 areas。',
+    ].join('\n');
+  }
+  if (mode === 'delta') {
+    return [
+      '$hive-lite-map-maintainer',
+      '请查看 map delta list，帮我判断哪些 delta 值得 apply，先不要自动 apply，等我确认。',
+    ].join('\n');
+  }
+  return [
+    '$hive-lite-map-maintainer',
+    '已有 map，请做一次 refresh，按 map health 修复 stale paths、scope、roles、verification。',
+  ].join('\n');
+}
+
+function splitStartPrompt(split) {
+  const phase = split.suggestedNextPhase;
+  return [
+    '$hive-lite-start-prompt',
+    `继续 split ${split.id}。`,
+    phase ? `建议下一 phase: ${phase.phaseId}` : '请先检查剩余 phase。',
+    phase && phase.findIntent ? `find intent: ${phase.findIntent}` : '',
+  ].filter(Boolean).join('\n');
+}
+
+function chooseSplit(status) {
+  const splits = status.recentSplitNotes || [];
+  return splits.find((split) => split.suggestedNextPhase) || null;
+}
+
+function requiredSkillForAction(actionItem) {
+  if (!actionItem) return null;
+  if (actionItem.kind === 'run_start_skill' || actionItem.kind === 'continue_split') return 'hive-lite-start-prompt';
+  if (actionItem.kind === 'run_finish_skill' || actionItem.kind === 'commit_accepted_change') return 'hive-lite-finish';
+  if (actionItem.kind === 'run_map_maintainer') return 'hive-lite-map-maintainer';
+  return null;
+}
+
+function applySkillPreflight(root, options, current) {
+  const requiredSkill = requiredSkillForAction(current.primaryAction);
+  const preflight = skillPreflight(root, requiredSkill, options);
+  if (!preflight) return { ...current, operatorSkillPreflight: null };
+  if (preflight.ready) return { ...current, operatorSkillPreflight: preflight };
+
+  const blockedAction = current.primaryAction;
+  return {
+    ...current,
+    phaseGuess: 'skill_preflight',
+    primaryAction: action({
+      kind: 'install_operator_skill',
+      label: `Install ${preflight.requiredSkill}`,
+      command: preflight.installCommand,
+      explanation: 'The recommended next operator step requires this Hive Lite skill in the selected agent target.',
+    }),
+    secondaryActions: [
+      action({
+        ...blockedAction,
+        enabled: false,
+        disabledReason: `Install ${preflight.requiredSkill} first for the selected agent target.`,
+      }),
+      ...current.secondaryActions,
+    ],
+    summaryForHuman: `需要先安装 ${preflight.requiredSkill}，然后再继续 Hive Lite operator flow。`,
+    summaryForAgent: `The selected agent target is missing ${preflight.requiredSkill}. Run skills install before using the handoff skill.`,
+    operatorSkillPreflight: preflight,
+  };
+}
+
+function evaluateNextAction(cwd, options = {}) {
+  const root = repoRoot(cwd);
+  const workspace = evaluateWorkspaceStatus(root);
+  const repoSetupRequired = workspace.hive.state === 'repo_setup_required';
+  const mapHealth = repoSetupRequired
+    ? { status: 'not_checked', critical: 0, warnings: 0, info: 0, areasChecked: 0, topFindings: [] }
+    : mapHealthSummary(root);
+  const latestChange = repoSetupRequired ? null : latestChangeSummary(root);
+  const deltas = repoSetupRequired ? [] : pendingDeltas(root);
+  const warnings = [];
+  const secondaryActions = [];
+
+  if (mapHealth.topFindings.length > 0) {
+    for (const finding of mapHealth.topFindings) {
+      if (finding.severity === 'critical' || finding.code === 'MAP_FILE_IGNORED') {
+        warnings.push(`${finding.code}: ${finding.message}`);
+      }
+    }
+  }
+
+  if (deltas.length > 0) {
+    secondaryActions.push(action({
+      kind: 'review_map_deltas',
+      label: 'Review pending map deltas',
+      command: 'hive-lite map delta list',
+      prompt: mapMaintainerPrompt('delta'),
+      explanation: `${deltas.length} pending map delta candidate(s) are available for human review.`,
+    }));
+  }
+
+  let phaseGuess = 'start';
+  let primaryAction = action({
+    kind: 'run_start_skill',
+    label: 'Use hive-lite-start-prompt',
+    prompt: startPrompt(),
+    explanation: 'The worktree is clean and Hive Lite is ready for a new bounded requirement.',
+  });
+  let summaryForHuman = '当前工作区干净，可以用 hive-lite-start-prompt 开始一个新的小需求。';
+  let summaryForAgent = 'Worktree is clean. Ask the human for the next requirement and use hive-lite-start-prompt.';
+
+  if (workspace.hive.state === 'repo_setup_required') {
+    phaseGuess = 'repo_setup_required';
+    primaryAction = action({
+      kind: 'repo_setup_required',
+      label: 'Stop: git repository required',
+      explanation: 'Hive Lite needs git before it can safely run find/check/accept. Switch to the correct repo root, or manually initialize git and create an initial commit before using Hive Lite.',
+    });
+    summaryForHuman = '当前目录不是 git repo。Hive Lite 不能安全开始；请切到正确的 repo 根目录，或你自己先完成 git 初始化和初始提交。';
+    summaryForAgent = 'No git repository detected. Stop. Do not run find/check/accept or initialize git automatically.';
+  } else if (!workspace.canStartNewRequirement) {
+    if (workspace.hive.state === 'in_progress') {
+      phaseGuess = 'finish';
+      primaryAction = action({
+        kind: 'run_finish_skill',
+        label: 'Use hive-lite-finish',
+        prompt: finishPrompt(workspace.hive.latestChange && workspace.hive.latestChange.id),
+        explanation: 'There is an in-progress Hive Change Record that should be checked, validated, or accepted before starting new work.',
+      });
+      summaryForHuman = '当前有一个 Hive change 还在进行中，建议先用 hive-lite-finish 收尾。';
+      summaryForAgent = 'There is an in-progress Hive change. Do not start a new requirement; use hive-lite-finish.';
+    } else if (workspace.hive.state === 'accepted_uncommitted') {
+      phaseGuess = 'finish';
+      primaryAction = action({
+        kind: 'commit_accepted_change',
+        label: 'Commit accepted Hive change',
+        command: workspace.hive.latestChange ? `hive-lite accept ${workspace.hive.latestChange.id} --commit -m "<message>"` : null,
+        prompt: finishPrompt(workspace.hive.latestChange && workspace.hive.latestChange.id),
+        explanation: 'The current dirty diff matches an accepted Hive change that still needs a git commit boundary.',
+      });
+      summaryForHuman = '当前 change 已经 accept，但还没有 commit。建议先用 finish/accept 创建提交边界。';
+      summaryForAgent = 'The latest Hive change is accepted but uncommitted. Ask the human before committing.';
+    } else {
+      phaseGuess = 'preflight';
+      primaryAction = action({
+        kind: 'resolve_dirty_worktree',
+        label: 'Resolve unmanaged dirty worktree',
+        command: 'hive-lite status',
+        explanation: 'The worktree has unmanaged dirty changes. Commit, stash, use a separate worktree, or stop before starting a Hive Lite requirement.',
+      });
+      summaryForHuman = '当前工作区有 unmanaged dirty diff，不建议开始新需求。请先 commit、stash、另开 worktree，或停止。';
+      summaryForAgent = 'Unmanaged dirty worktree. Do not run find for a new requirement until the human chooses how to isolate the changes.';
+    }
+  } else if (mapHealth.status === 'invalid_map' || mapHealth.critical > 0) {
+    phaseGuess = 'map';
+    primaryAction = action({
+      kind: 'run_map_maintainer',
+      label: 'Use hive-lite-map-maintainer',
+      prompt: mapMaintainerPrompt(mapHealth.areasChecked === 0 ? 'bootstrap' : 'refresh'),
+      explanation: 'Project Map health has critical findings, so find/check may not produce safe context or evidence policy.',
+    });
+    summaryForHuman = 'Project Map 目前有 critical 问题，建议先用 hive-lite-map-maintainer 修 map。';
+    summaryForAgent = 'Project Map has critical health findings. Do not start coding work; run map maintainer flow.';
+  } else if (mapHealth.status === 'needs_attention') {
+    phaseGuess = 'map';
+    primaryAction = action({
+      kind: 'run_map_maintainer',
+      label: 'Use hive-lite-map-maintainer',
+      prompt: mapMaintainerPrompt('refresh'),
+      explanation: 'Project Map is usable but has warnings that may reduce find/check quality.',
+    });
+    summaryForHuman = 'Project Map 可用但有 warning。建议先 refresh map，或者在明确知道风险时继续 start。';
+    summaryForAgent = 'Project Map needs attention. Prefer map maintainer before new work, unless the human chooses to proceed.';
+    secondaryActions.unshift(action({
+      kind: 'run_start_skill',
+      label: 'Start anyway with caution',
+      prompt: startPrompt(),
+      explanation: 'Use only if the warnings are not relevant to the next requirement.',
+    }));
+  } else {
+    const split = chooseSplit(workspace);
+    if (split) {
+      phaseGuess = 'split_continue';
+      primaryAction = action({
+        kind: 'continue_split',
+        label: 'Continue recent split note',
+        prompt: splitStartPrompt(split),
+        explanation: 'A recent large intent was decomposed and has a ready remaining phase.',
+      });
+      summaryForHuman = `发现未完成的 split note：${split.id}。建议继续 ready phase，而不是重新开一个大需求。`;
+      summaryForAgent = 'A recent split note has a ready phase. Ask the human whether to continue it via hive-lite-start-prompt.';
+    }
+  }
+
+  const withSkillPreflight = applySkillPreflight(root, options, {
+    phaseGuess,
+    summaryForHuman,
+    summaryForAgent,
+    primaryAction,
+    secondaryActions,
+  });
+
+  return {
+    version: 1,
+    command: 'next',
+    generatedAt: new Date().toISOString(),
+    root,
+    phaseGuess: withSkillPreflight.phaseGuess,
+    summaryForHuman: withSkillPreflight.summaryForHuman,
+    summaryForAgent: withSkillPreflight.summaryForAgent,
+    primaryAction: withSkillPreflight.primaryAction,
+    secondaryActions: withSkillPreflight.secondaryActions,
+    warnings,
+    operatorSkillPreflight: withSkillPreflight.operatorSkillPreflight,
+    state: {
+      branch: workspace.branch,
+      head: workspace.head,
+      worktree: workspace.worktree,
+      hive: workspace.hive,
+      canStartNewRequirement: workspace.canStartNewRequirement,
+      latestChange,
+      mapHealth,
+      pendingMapDeltas: deltas.map((delta) => ({
+        id: delta.id,
+        type: delta.type,
+        status: delta.status,
+        target: delta.target || null,
+      })),
+      recentSplitNotes: workspace.recentSplitNotes || [],
+      splitNoteSummary: workspace.splitNoteSummary || null,
+    },
+  };
+}
+
+module.exports = {
+  evaluateNextAction,
+};

package/src/lib/risk.js

@@ -0,0 +1,122 @@
+const { firstPatternMatch } = require('./glob');
+
+function normalizePath(value) {
+  return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function validationSurfaceWeakened(diff) {
+  if (!diff || !diff.trim()) return false;
+  const removedValidationCommand = /^-[^-].*\b(test|tests|lint|typecheck|tsc|vitest|jest|eslint|prettier|coverage|check|checks)\b/im.test(diff);
+  const addedBypass = /^\+[^+].*(continue-on-error:\s*true|allow_failure:\s*true|\|\|\s*true|&&\s*true\b|exit\s+0\b|--no-verify\b|--passWithNoTests\b|skip[-_ ]?(tests?|checks?|validation)|disable[-_ ]?(tests?|checks?|validation))/im.test(diff);
+  return removedValidationCommand || addedBypass;
+}
+
+function defaultSensitiveReason(file) {
+  const normalized = normalizePath(file);
+  const patterns = [
+    [/(\b|\/)(auth|oauth|session|sessions|permission|permissions|rbac|acl)(\/|\.|$)/i, 'auth_or_permissions'],
+    [/(\b|\/)(payment|payments|billing|stripe|invoice|invoices)(\/|\.|$)/i, 'payment_or_billing'],
+    [/(\b|\/)(security|secrets?|credentials?|pii|privacy|encrypt|encryption|crypto)(\/|\.|$)/i, 'security_or_privacy'],
+    [/(\b|\/)(migrations?|drizzle)(\/|$)|(^|\/)schema\.sql$/i, 'db_or_migration'],
+    [/(^|\/)(\.github\/workflows|\.gitlab-ci\.yml|Dockerfile|docker-compose|deploy|deployment|infra|k8s|helm)(\/|\.|$)/i, 'ci_cd_or_deploy'],
+    [/(^|\/)(package\.json|bun\.lock|pnpm-lock\.yaml|yarn\.lock|package-lock\.json)$/i, 'dependency_surface'],
+  ];
+  const hit = patterns.find(([regex]) => regex.test(normalized));
+  return hit ? hit[1] : null;
+}
+
+function configuredMatches(files, policies) {
+  return files.map((file) => ({ file, policy: firstPatternMatch(file, policies || []) })).filter((item) => item.policy);
+}
+
+function validationStatus(change) {
+  const results = (change.validation && change.validation.results) || [];
+  if (results.some((result) => result.status === 'failed' || result.exitCode > 0)) return 'failed';
+  if (results.length > 0 && results.every((result) => result.status === 'passed' || result.exitCode === 0)) return 'passed';
+  return change.validation ? change.validation.status || 'not_run' : 'not_run';
+}
+
+function hasRequiredValidation(change) {
+  const plan = change.validation && change.validation.plan ? change.validation.plan : [];
+  return plan.some((item) => item.required !== false && item.type !== 'manual' && item.command);
+}
+
+function evaluateChangeRisk(change, map) {
+  const files = (change.diff.changedFiles || []).map((item) => item.path || item);
+  const diff = change.diff.text || '';
+  const blockingReasons = [];
+  const reviewReasons = [];
+  const signals = [];
+
+  if (!change.repo.baselineCommit) blockingReasons.push('missing baseline commit');
+  if (files.length > 0 && !diff.trim()) blockingReasons.push('diff could not be captured for changed files');
+
+  if (change.scope.status === 'violation') {
+    blockingReasons.push(`scope violation: ${change.scope.violations.join(', ')}`);
+  }
+
+  const status = validationStatus(change);
+  if (status === 'failed') blockingReasons.push('validation failed');
+
+  if (validationSurfaceWeakened(diff)) {
+    blockingReasons.push('diff appears to weaken validation, CI, or deploy checks');
+  }
+
+  const configuredSensitive = configuredMatches(files, map.rules.sensitive_paths || []);
+  for (const match of configuredSensitive) {
+    reviewReasons.push(`sensitive path (${match.policy.reason || match.policy.pattern}): ${match.file}`);
+  }
+
+  const codeOwner = configuredMatches(files, map.rules.code_owner_paths || []);
+  for (const match of codeOwner) {
+    const owners = match.policy.owners ? ` -> ${match.policy.owners.join(', ')}` : '';
+    reviewReasons.push(`code-owner path${owners}: ${match.file}`);
+  }
+
+  const security = configuredMatches(files, map.rules.security_review_paths || []);
+  for (const match of security) {
+    reviewReasons.push(`security-review path: ${match.file}`);
+  }
+
+  for (const file of files) {
+    const reason = defaultSensitiveReason(file);
+    if (reason) reviewReasons.push(`${reason}: ${file}`);
+  }
+
+  if (change.scope.status === 'unknown' || change.scope.status === 'needs_review') {
+    reviewReasons.push(`scope ${change.scope.status}`);
+  }
+
+  const areaIds = new Set((change.scope.matchedAreas || []).filter(Boolean));
+  if (areaIds.size > 1) reviewReasons.push('change spans multiple map areas');
+  if (files.length > 8) reviewReasons.push(`changed file count ${files.length} exceeds light-change threshold`);
+
+  if (files.length === 0) signals.push('no changed files');
+  else if (files.length === 1) signals.push('single file change');
+  else signals.push(`${files.length} files changed`);
+
+  const requiresValidation = hasRequiredValidation(change);
+  let verdict = 'acceptable';
+  if (blockingReasons.length > 0) verdict = 'blocked';
+  else if (requiresValidation && status === 'not_run') verdict = 'needs_validation';
+  else if (reviewReasons.length > 0) verdict = 'needs_review';
+
+  const level = blockingReasons.length > 0 ? 'high'
+    : reviewReasons.length > 0 ? 'medium'
+      : files.length <= 2 ? 'low'
+        : 'medium';
+
+  return {
+    verdict,
+    level,
+    blockingReasons: [...new Set(blockingReasons)],
+    reviewReasons: [...new Set(reviewReasons)],
+    signals: [...new Set(signals)],
+    evaluatedAt: new Date().toISOString(),
+  };
+}
+
+module.exports = {
+  evaluateChangeRisk,
+  validationStatus,
+};

package/src/lib/roles.js

@@ -0,0 +1,109 @@
+const ROLE_TAXONOMY = [
+  'page',
+  'ui_component',
+  'styles',
+  'state_store',
+  'grouping_logic',
+  'data_transform',
+  'api_contract',
+  'schema_logic',
+  'cli_behavior',
+  'error_handling',
+  'cache_logic',
+  'config',
+  'docs',
+  'test',
+  'unknown',
+];
+
+const ROLE_SET = new Set(ROLE_TAXONOMY);
+
+const ROLE_ALIASES = new Map([
+  ['main_component', 'ui_component'],
+  ['item_component', 'ui_component'],
+  ['component', 'ui_component'],
+  ['view', 'ui_component'],
+  ['ui', 'ui_component'],
+  ['main_page', 'page'],
+  ['copy', 'docs'],
+  ['parser', 'data_transform'],
+  ['formatter', 'data_transform'],
+  ['code', 'unknown'],
+  ['file', 'unknown'],
+  ['entrypoint', 'unknown'],
+  ['grep_hit', 'unknown'],
+]);
+
+const UI_MANUAL_ROLES = new Set(['page', 'ui_component', 'styles', 'docs']);
+const INTERNAL_BEHAVIOR_ROLES = new Set([
+  'state_store',
+  'grouping_logic',
+  'data_transform',
+  'api_contract',
+  'schema_logic',
+  'cli_behavior',
+  'error_handling',
+  'cache_logic',
+]);
+
+function normalizeRole(role) {
+  const raw = String(role || '').trim();
+  if (!raw) return '';
+  if (ROLE_SET.has(raw)) return raw;
+  return ROLE_ALIASES.get(raw) || '';
+}
+
+function isKnownRole(role) {
+  return Boolean(normalizeRole(role));
+}
+
+function isCanonicalRole(role) {
+  return ROLE_SET.has(String(role || '').trim());
+}
+
+function isUiManualRole(role) {
+  return UI_MANUAL_ROLES.has(normalizeRole(role));
+}
+
+function isInternalBehaviorRole(role) {
+  return INTERNAL_BEHAVIOR_ROLES.has(normalizeRole(role));
+}
+
+function inferRoleFromPath(filePath) {
+  const file = String(filePath || '').replace(/\\/g, '/').toLowerCase();
+  const base = file.split('/').pop() || '';
+
+  if (/(^|\/)(__tests__|tests?|specs?)\//.test(file) || /\.(test|spec)\.[cm]?[jt]sx?$/.test(base)) return 'test';
+  if (/\.(css|scss|sass|less)$/.test(base)) return 'styles';
+  if (/\.(md|mdx|txt)$/.test(base) || /(^|\/)docs?\//.test(file) || /(^|\/)readme(\.|$)/.test(file)) return 'docs';
+  if (/\.github\/workflows\//.test(file) || /(^|\/)config\//.test(file) || /\.config\./.test(base) || /(^|\/)package\.json$/.test(file) || /lock$|lock\.yaml$|lock\.json$/.test(base)) return 'config';
+  if (/(^|\/)(cli|commands|bin)\//.test(file)) return 'cli_behavior';
+  if (/(^|\/)(stores?|state)\//.test(file) || /store\.[cm]?[jt]sx?$/.test(base)) return 'state_store';
+  if (/(schema|zod|contract|contracts|types?)/.test(file)) {
+    return /(api|contract|contracts)/.test(file) ? 'api_contract' : 'schema_logic';
+  }
+  if (/(group|grouping|sort|filter|partition)/.test(base)) return 'grouping_logic';
+  if (/(transform|normalize|mapper|serializer|deserialize|format)/.test(base)) return 'data_transform';
+  if (/(error|retry|exception|fallback|recover)/.test(base)) return 'error_handling';
+  if (/(cache|memo|storage)/.test(base)) return 'cache_logic';
+  if (/(^|\/)(pages?|views?|routes?)\//.test(file) || /page\.[cm]?[jt]sx?$/.test(base)) return 'page';
+  if (/(^|\/)components?\//.test(file) || /\.(vue|svelte|tsx|jsx)$/.test(base)) return 'ui_component';
+
+  return 'unknown';
+}
+
+function roleListText() {
+  return ROLE_TAXONOMY.join(', ');
+}
+
+module.exports = {
+  ROLE_TAXONOMY,
+  ROLE_SET,
+  normalizeRole,
+  isKnownRole,
+  isCanonicalRole,
+  isUiManualRole,
+  isInternalBehaviorRole,
+  inferRoleFromPath,
+  roleListText,
+};