hive-lite 0.1.9 → 0.2.0

package/src/lib/intent.js

@@ -0,0 +1,620 @@
+const fs = require('fs');
+const path = require('path');
+const { ensureDir, exists, readJson, readText, writeJson, writeText } = require('./fsx');
+const { parseYaml } = require('./yaml');
+
+const SCHEMA_VERSION = 'hive.start_intent.v1';
+const INTENT_ID_PATTERN = /^int_[a-z0-9][a-z0-9_-]*$/;
+
+const REQUIRED_SECTIONS = [
+  {
+    key: 'originalIdea',
+    title: 'Original Idea',
+    aliases: ['original idea'],
+    allowNone: false,
+  },
+  {
+    key: 'agreedDirection',
+    title: 'Agreed Direction',
+    aliases: ['agreed direction'],
+    allowNone: false,
+  },
+  {
+    key: 'userConfirmedDecisions',
+    title: 'User-Confirmed Decisions',
+    aliases: ['user confirmed decisions', 'user-confirmed decisions'],
+    allowNone: true,
+  },
+  {
+    key: 'nonGoals',
+    title: 'Non-Goals',
+    aliases: ['non goals', 'non-goals'],
+    allowNone: false,
+  },
+  {
+    key: 'acceptanceSignals',
+    title: 'Acceptance Signals',
+    aliases: ['acceptance signals'],
+    allowNone: false,
+  },
+  {
+    key: 'unknownsForHiveLiteToResolve',
+    title: 'Unknowns For Hive Lite To Resolve',
+    aliases: ['unknowns for hive lite to resolve'],
+    allowNone: false,
+  },
+  {
+    key: 'preHiveObservationsHints',
+    title: 'Pre-Hive Observations / Hints',
+    aliases: [
+      'pre hive observations hints',
+      'pre-hive observations hints',
+      'pre hive observations',
+      'pre-hive observations',
+      'pre hive hints',
+      'pre-hive hints',
+    ],
+    allowNone: true,
+  },
+  {
+    key: 'blockingQuestions',
+    title: 'Blocking Questions',
+    aliases: ['blocking questions'],
+    allowNone: true,
+  },
+];
+
+const SECTION_BY_NORMALIZED = new Map();
+for (const section of REQUIRED_SECTIONS) {
+  for (const alias of section.aliases) SECTION_BY_NORMALIZED.set(normalizeHeading(alias), section);
+}
+
+const FORBIDDEN_SECTION_HEADINGS = new Map([
+  ['direct writable', 'Direct Writable'],
+  ['final file scope', 'Final File Scope'],
+  ['implementation plan', 'Implementation Plan'],
+  ['validation plan', 'Validation Plan'],
+  ['files to modify', 'Files To Modify'],
+  ['files to edit', 'Files To Edit'],
+  ['files to change', 'Files To Change'],
+  ['edit targets', 'Edit Targets'],
+  ['coding agent prompt', 'Coding Agent Prompt'],
+]);
+
+const EXECUTION_INSTRUCTION_PATTERNS = [
+  {
+    code: 'AGENT_EDIT_INSTRUCTION',
+    pattern: /\bagent\s+(should|must|will|can)\s+(edit|modify|change|update|touch)\b/i,
+    message: 'Start Intent Handoff must not instruct the coding agent to edit files.',
+  },
+  {
+    code: 'CHANGE_THESE_FILES',
+    pattern: /\b(edit|modify|change|update|touch)\s+these\s+files\b/i,
+    message: 'Start Intent Handoff must not define files for implementation.',
+  },
+  {
+    code: 'FILES_TO_MODIFY',
+    pattern: /\bfiles\s+to\s+(modify|edit|change|update)\b/i,
+    message: 'Start Intent Handoff must not include a files-to-modify list.',
+  },
+  {
+    code: 'DIRECT_FILE_EDIT_TARGET',
+    pattern: /\b(edit|modify|change|update|touch)\s+`?([A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+`?/i,
+    message: 'Start Intent Handoff may mention files only as non-authoritative hints, not edit targets.',
+  },
+  {
+    code: 'DIRECT_FILE_EDIT_TARGET',
+    pattern: /`?([A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+`?\s+(must|should|will)\s+be\s+(edited|modified|changed|updated|touched)/i,
+    message: 'Start Intent Handoff may mention files only as non-authoritative hints, not edit targets.',
+  },
+];
+
+const EXECUTION_LABEL_PATTERN = /^\s*(Direct Writable|Final File Scope|Implementation Plan|Validation Plan|Files To Modify|Files To Edit|Files To Change|Edit Targets)\s*:/i;
+const FILE_PATH_PATTERN = /(?:^|[\s(`])(?:\.?\.?\/)?(?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+\.[A-Za-z0-9]+(?:$|[\s`).,;:])/;
+const HINT_LANGUAGE_PATTERN = /\b(may|might|appears?|observed|verify|possible|likely|seems?|non-authoritative|hint|hints|could)\b/i;
+const CODEBASE_UNKNOWN_PATTERN = /\b(codebase|repo|repository|project|existing|current|where|which|file|path|module|component|provider|proxy|controller|service|dto|config|configuration|test|registration|registry|abstraction|pattern|endpoint|route|schema|database|table|api|surface|integration|class|function|hook|entrypoint|workflow|model)\b/i;
+const PRODUCT_DECISION_PATTERN = /\b(should|whether|decide|choose|allow users|users can|user can|paid|free|pricing|tier|plan|rollout|brand|policy|v1|first version|support multiple|enable for)\b/i;
+
+function normalizeHeading(value) {
+  return String(value || '')
+    .toLowerCase()
+    .replace(/[’']/g, '')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+}
+
+function isNone(value) {
+  return /^(none|none\.|n\/a|no blocking questions\.?)$/i.test(String(value || '').trim());
+}
+
+function cleanHeadingText(value) {
+  return String(value || '').replace(/\s+#+\s*$/g, '').trim();
+}
+
+function parseFrontmatter(markdown) {
+  const normalized = String(markdown || '').replace(/^\uFEFF/, '');
+  const lines = normalized.split(/\r?\n/);
+  if (lines[0].trim() !== '---') {
+    return {
+      frontmatter: {},
+      body: normalized,
+      errors: [{
+        code: 'MISSING_FRONTMATTER',
+        message: 'Start Intent Handoff must begin with YAML frontmatter.',
+      }],
+    };
+  }
+
+  let end = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') {
+      end = i;
+      break;
+    }
+  }
+
+  if (end === -1) {
+    return {
+      frontmatter: {},
+      body: normalized,
+      errors: [{
+        code: 'UNCLOSED_FRONTMATTER',
+        message: 'Start Intent Handoff frontmatter must be closed with ---.',
+      }],
+    };
+  }
+
+  try {
+    return {
+      frontmatter: parseYaml(lines.slice(1, end).join('\n')),
+      body: lines.slice(end + 1).join('\n'),
+      errors: [],
+    };
+  } catch (error) {
+    return {
+      frontmatter: {},
+      body: lines.slice(end + 1).join('\n'),
+      errors: [{
+        code: 'INVALID_FRONTMATTER',
+        message: `Start Intent Handoff frontmatter is invalid: ${error.message}`,
+      }],
+    };
+  }
+}
+
+function parseMarkdownSections(body) {
+  const sections = {};
+  const allHeadings = [];
+  let title = '';
+  let active = null;
+
+  for (const line of String(body || '').split(/\r?\n/)) {
+    const h1 = line.match(/^#\s+(.+)$/);
+    if (h1 && !title) {
+      title = cleanHeadingText(h1[1]);
+      allHeadings.push({ level: 1, text: title, normalized: normalizeHeading(title) });
+      active = null;
+      continue;
+    }
+
+    const h2 = line.match(/^##\s+(.+)$/);
+    if (h2) {
+      const text = cleanHeadingText(h2[1]);
+      const normalized = normalizeHeading(text);
+      allHeadings.push({ level: 2, text, normalized });
+      const known = SECTION_BY_NORMALIZED.get(normalized);
+      active = known ? known.key : `__unknown_${allHeadings.length}`;
+      if (!sections[active]) {
+        sections[active] = {
+          title: known ? known.title : text,
+          rawTitle: text,
+          content: '',
+        };
+      }
+      continue;
+    }
+
+    if (active) sections[active].content += `${line}\n`;
+  }
+
+  for (const section of Object.values(sections)) {
+    section.content = section.content.trim();
+  }
+
+  return { title, sections, allHeadings };
+}
+
+function addError(errors, code, message, extra = {}) {
+  errors.push({ code, message, ...extra });
+}
+
+function addWarning(warnings, code, message, extra = {}) {
+  warnings.push({ code, message, ...extra });
+}
+
+function contentLines(section) {
+  return String(section && section.content ? section.content : '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function contentItems(section) {
+  return contentLines(section)
+    .map((line) => line.replace(/^[-*]\s+/, '').trim())
+    .filter((line) => !isNone(line));
+}
+
+function validateFrontmatter(frontmatter, errors) {
+  if (frontmatter.type !== 'hive-lite.start-intent') {
+    addError(errors, 'INVALID_TYPE', 'frontmatter.type must be hive-lite.start-intent.', { field: 'type' });
+  }
+  if (Number(frontmatter.version) !== 1) {
+    addError(errors, 'INVALID_VERSION', 'frontmatter.version must be 1.', { field: 'version' });
+  }
+  if (frontmatter.status !== 'ready_for_hive') {
+    addError(errors, 'INVALID_STATUS', 'frontmatter.status must be ready_for_hive.', { field: 'status' });
+  }
+  if (!frontmatter.source) {
+    addError(errors, 'MISSING_SOURCE', 'frontmatter.source is required.', { field: 'source' });
+  }
+  if (!frontmatter.intent_id) {
+    addError(errors, 'MISSING_INTENT_ID', 'frontmatter.intent_id is required.', { field: 'intent_id' });
+  } else if (!INTENT_ID_PATTERN.test(String(frontmatter.intent_id))) {
+    addError(errors, 'INVALID_INTENT_ID', 'frontmatter.intent_id must match int_[a-z0-9][a-z0-9_-]*.', { field: 'intent_id' });
+  }
+  if (!frontmatter.created_at) {
+    addError(errors, 'MISSING_CREATED_AT', 'frontmatter.created_at is required.', { field: 'created_at' });
+  } else if (Number.isNaN(Date.parse(String(frontmatter.created_at)))) {
+    addError(errors, 'INVALID_CREATED_AT', 'frontmatter.created_at must be an ISO-like timestamp.', { field: 'created_at' });
+  }
+}
+
+function validateSections(parsed, frontmatter, errors, warnings) {
+  if (!parsed.title) {
+    addError(errors, 'MISSING_TITLE', 'Start Intent Handoff must include an H1 title.');
+  } else if (!/^Start Intent Handoff:/i.test(parsed.title)) {
+    addWarning(warnings, 'TITLE_FORMAT', 'H1 should start with "Start Intent Handoff:".');
+  }
+
+  for (const heading of parsed.allHeadings.filter((item) => item.level === 2)) {
+    const forbidden = FORBIDDEN_SECTION_HEADINGS.get(heading.normalized);
+    if (forbidden) {
+      addError(errors, 'FORBIDDEN_SECTION', `Start Intent Handoff must not include execution-only section "${forbidden}".`, {
+        section: heading.text,
+      });
+    }
+  }
+
+  for (const required of REQUIRED_SECTIONS) {
+    const section = parsed.sections[required.key];
+    if (!section) {
+      addError(errors, 'MISSING_SECTION', `Missing required section: ${required.title}.`, { section: required.title });
+      continue;
+    }
+    if (!section.content || (!required.allowNone && isNone(section.content))) {
+      addError(errors, 'EMPTY_SECTION', `${required.title} must not be empty.`, { section: required.title });
+    }
+  }
+
+  const blocking = parsed.sections.blockingQuestions;
+  if (frontmatter.status === 'ready_for_hive' && blocking && !isNone(blocking.content)) {
+    addError(errors, 'BLOCKING_QUESTIONS_PRESENT', 'ready_for_hive handoff must have Blocking Questions set to None.', {
+      section: 'Blocking Questions',
+    });
+  }
+
+  const unknowns = parsed.sections.unknownsForHiveLiteToResolve;
+  if (unknowns) {
+    const items = contentItems(unknowns);
+    if (items.length === 0) {
+      addError(errors, 'EMPTY_CODEBASE_UNKNOWNS', 'Unknowns For Hive Lite To Resolve must list codebase/context unknowns.', {
+        section: 'Unknowns For Hive Lite To Resolve',
+      });
+    }
+    for (const item of items) {
+      if (PRODUCT_DECISION_PATTERN.test(item)) {
+        addError(errors, 'PRODUCT_DECISION_IN_UNKNOWNS', 'Product decisions belong in User-Confirmed Decisions or Blocking Questions, not Unknowns For Hive Lite To Resolve.', {
+          section: 'Unknowns For Hive Lite To Resolve',
+          text: item,
+        });
+      } else if (!CODEBASE_UNKNOWN_PATTERN.test(item)) {
+        addWarning(warnings, 'UNKNOWN_MAY_NOT_BE_CODEBASE_CONTEXT', 'Unknowns For Hive Lite To Resolve should be codebase/context questions only.', {
+          section: 'Unknowns For Hive Lite To Resolve',
+          text: item,
+        });
+      }
+    }
+  }
+}
+
+function validateExecutionContent(markdown, parsed, errors, warnings) {
+  for (const rule of EXECUTION_INSTRUCTION_PATTERNS) {
+    const match = String(markdown || '').match(rule.pattern);
+    if (match) {
+      addError(errors, rule.code, rule.message, { text: match[0] });
+    }
+  }
+
+  for (const [key, section] of Object.entries(parsed.sections)) {
+    for (const line of contentLines(section)) {
+      const labelMatch = line.match(EXECUTION_LABEL_PATTERN);
+      if (labelMatch) {
+        addError(errors, 'FORBIDDEN_EXECUTION_LABEL', `Start Intent Handoff must not include execution-only label "${labelMatch[1]}".`, {
+          section: section.title,
+          text: line,
+        });
+        continue;
+      }
+      if (!FILE_PATH_PATTERN.test(line)) continue;
+      if (key === 'preHiveObservationsHints') {
+        if (!HINT_LANGUAGE_PATTERN.test(line)) {
+          addWarning(warnings, 'AUTHORITATIVE_FILE_HINT', 'File paths in Pre-Hive Observations / Hints should be explicitly non-authoritative.', {
+            section: section.title,
+            text: line,
+          });
+        }
+      } else {
+        addWarning(warnings, 'FILE_PATH_OUTSIDE_HINTS', 'File paths should usually appear only as non-authoritative Pre-Hive Observations / Hints.', {
+          section: section.title,
+          text: line,
+        });
+      }
+    }
+  }
+}
+
+function deriveFindIntent(fields) {
+  const parts = [
+    ['Agreed Direction', fields.agreedDirection],
+    ['User-Confirmed Decisions', fields.userConfirmedDecisions],
+    ['Non-Goals', fields.nonGoals],
+    ['Acceptance Signals', fields.acceptanceSignals],
+    ['Codebase Unknowns For Hive Lite To Resolve', fields.unknownsForHiveLiteToResolve],
+  ].filter(([, value]) => value && !isNone(value));
+
+  return parts.map(([label, value]) => `${label}:\n${value}`).join('\n\n');
+}
+
+function parseStartIntentMarkdown(markdown) {
+  const front = parseFrontmatter(markdown);
+  const parsed = parseMarkdownSections(front.body);
+  const fields = {};
+  for (const section of REQUIRED_SECTIONS) {
+    fields[section.key] = parsed.sections[section.key] ? parsed.sections[section.key].content : '';
+  }
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    title: parsed.title,
+    frontmatter: front.frontmatter,
+    fields,
+    findIntent: deriveFindIntent(fields),
+    _parse: {
+      title: parsed.title,
+      frontmatterErrors: front.errors,
+      sections: parsed.sections,
+      allHeadings: parsed.allHeadings,
+    },
+  };
+}
+
+function validateStartIntentMarkdown(markdown) {
+  const intent = parseStartIntentMarkdown(markdown);
+  const errors = [...intent._parse.frontmatterErrors];
+  const warnings = [];
+
+  validateFrontmatter(intent.frontmatter, errors);
+  validateSections(intent._parse, intent.frontmatter, errors, warnings);
+  validateExecutionContent(markdown, intent._parse, errors, warnings);
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    valid: errors.length === 0,
+    intent_id: intent.frontmatter.intent_id || null,
+    status: intent.frontmatter.status || null,
+    errors,
+    warnings,
+    intent: publicIntent(intent),
+  };
+}
+
+function publicIntent(intent) {
+  return {
+    schema_version: SCHEMA_VERSION,
+    intent_id: intent.frontmatter.intent_id || null,
+    type: intent.frontmatter.type || null,
+    version: intent.frontmatter.version || null,
+    status: intent.frontmatter.status || null,
+    source: intent.frontmatter.source || null,
+    created_at: intent.frontmatter.created_at || null,
+    title: intent.title || null,
+    fields: intent.fields,
+    findIntent: intent.findIntent,
+  };
+}
+
+function relPath(root, file) {
+  const realRoot = fs.realpathSync(root);
+  let realFile = path.resolve(file);
+  try {
+    realFile = fs.realpathSync(file);
+  } catch {
+    realFile = path.resolve(file);
+  }
+  const relative = path.relative(realRoot, realFile).replace(/\\/g, '/');
+  if (!relative || relative.startsWith('..')) return file;
+  return relative;
+}
+
+function intentDir(root, intentId) {
+  return path.join(root, '.hive', 'state', 'intents', intentId);
+}
+
+function savedIntentPaths(root, intentId) {
+  const dir = intentDir(root, intentId);
+  return {
+    dir,
+    markdownPath: path.join(dir, 'start-intent.md'),
+    jsonPath: path.join(dir, 'start-intent.json'),
+  };
+}
+
+function resolveIntentTarget(root, cwd, idOrPath) {
+  if (!idOrPath) throw new Error('intent id or path is required');
+
+  const text = String(idOrPath);
+  const candidates = path.isAbsolute(text)
+    ? [text]
+    : [path.resolve(cwd || root, text), path.resolve(root, text)];
+  const candidate = candidates.find((item, index) => (
+    exists(item) && candidates.indexOf(item) === index
+  ));
+  if (candidate) {
+    const stat = fs.statSync(candidate);
+    if (stat.isDirectory()) {
+      return {
+        kind: 'path',
+        markdownPath: path.join(candidate, 'start-intent.md'),
+        jsonPath: path.join(candidate, 'start-intent.json'),
+      };
+    }
+    if (path.basename(candidate) === 'start-intent.json') {
+      return {
+        kind: 'path',
+        markdownPath: path.join(path.dirname(candidate), 'start-intent.md'),
+        jsonPath: candidate,
+      };
+    }
+    return {
+      kind: 'path',
+      markdownPath: candidate,
+      jsonPath: path.join(path.dirname(candidate), 'start-intent.json'),
+    };
+  }
+
+  if (text.includes('/') || text.includes('\\') || text.endsWith('.md') || text.endsWith('.json')) {
+    throw new Error(`intent path does not exist: ${text}`);
+  }
+  if (!INTENT_ID_PATTERN.test(text)) {
+    throw new Error(`invalid intent id: ${text}`);
+  }
+
+  return {
+    kind: 'id',
+    intentId: text,
+    ...savedIntentPaths(root, text),
+  };
+}
+
+function readIntentTarget(root, cwd, idOrPath) {
+  const target = resolveIntentTarget(root, cwd, idOrPath);
+  if (!exists(target.markdownPath)) {
+    throw new Error(`Start Intent Handoff markdown not found: ${target.markdownPath}`);
+  }
+  const markdown = readText(target.markdownPath);
+  const validation = validateStartIntentMarkdown(markdown);
+  return {
+    ...validation.intent,
+    markdown,
+    paths: {
+      markdown: relPath(root, target.markdownPath),
+      json: exists(target.jsonPath) ? relPath(root, target.jsonPath) : null,
+    },
+    validation: {
+      valid: validation.valid,
+      errors: validation.errors,
+      warnings: validation.warnings,
+    },
+  };
+}
+
+function validateIntentTarget(root, cwd, idOrPath) {
+  const target = resolveIntentTarget(root, cwd, idOrPath);
+  if (!exists(target.markdownPath)) {
+    throw new Error(`Start Intent Handoff markdown not found: ${target.markdownPath}`);
+  }
+  const markdown = readText(target.markdownPath);
+  const validation = validateStartIntentMarkdown(markdown);
+  return {
+    schema_version: SCHEMA_VERSION,
+    command: 'intent validate',
+    target: idOrPath,
+    paths: {
+      markdown: relPath(root, target.markdownPath),
+      json: exists(target.jsonPath) ? relPath(root, target.jsonPath) : null,
+    },
+    valid: validation.valid,
+    intent_id: validation.intent_id,
+    status: validation.status,
+    errors: validation.errors,
+    warnings: validation.warnings,
+    intent: validation.intent,
+  };
+}
+
+function saveStartIntent(root, markdown, options = {}) {
+  const validation = validateStartIntentMarkdown(markdown);
+  if (!validation.valid) {
+    return {
+      schema_version: SCHEMA_VERSION,
+      command: 'intent save',
+      saved: false,
+      source: options.source || null,
+      valid: false,
+      intent_id: validation.intent_id,
+      status: validation.status,
+      errors: validation.errors,
+      warnings: validation.warnings,
+    };
+  }
+
+  const paths = savedIntentPaths(root, validation.intent_id);
+  ensureDir(paths.dir);
+  const markdownValue = String(markdown || '').endsWith('\n') ? String(markdown || '') : `${markdown}\n`;
+  writeText(paths.markdownPath, markdownValue);
+
+  const json = {
+    ...validation.intent,
+    paths: {
+      markdown: relPath(root, paths.markdownPath),
+      json: relPath(root, paths.jsonPath),
+    },
+    validation: {
+      valid: true,
+      errors: [],
+      warnings: validation.warnings,
+    },
+  };
+  writeJson(paths.jsonPath, json);
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    command: 'intent save',
+    saved: true,
+    source: options.source || null,
+    intent_id: validation.intent_id,
+    status: validation.status,
+    paths: json.paths,
+    warnings: validation.warnings,
+    intent: json,
+  };
+}
+
+function loadSavedIntentJson(root, cwd, idOrPath) {
+  const target = resolveIntentTarget(root, cwd, idOrPath);
+  if (!exists(target.jsonPath)) return null;
+  return readJson(target.jsonPath);
+}
+
+module.exports = {
+  INTENT_ID_PATTERN,
+  SCHEMA_VERSION,
+  deriveFindIntent,
+  loadSavedIntentJson,
+  parseStartIntentMarkdown,
+  readIntentTarget,
+  saveStartIntent,
+  validateIntentTarget,
+  validateStartIntentMarkdown,
+};