@hone-ai/cli 1.4.0

package/lib/learnings-parse.js

@@ -0,0 +1,331 @@
+'use strict';
+/**
+ * learnings-parse.js — H-035 schema-aware parser + write-back for the
+ * 3 active learnings YAML schemas. Pure helpers: callers do all I/O.
+ *
+ * Schemas (verified on hone-server + OptionsFlow develop, 2026-04-28):
+ *   A) top-level list of items                       (legacy, OptionsFlow E13-A → E26-A)
+ *   B) dict with `enterprise_candidates: [...]`      (OptionsFlow E25-A onward)
+ *   C) dict with `learnings: [...]`                  (hone-server H-001 onward)
+ *
+ * Without this module, `hone promote` only sees Schema A — Schemas B and C
+ * are silently dropped (no error, no warning), leading to invisible promotion
+ * data loss. Confirmed today: hone-server's own H-001/H-002a/H-003 learnings
+ * are 100% invisible to `hone promote` on develop@a549651.
+ *
+ * H-035 is the COMPATIBILITY SHIM that buys time for E29-H schema v2 to ship
+ * cleanly without breaking any production adopter. See
+ * docs/sdlc/PIPELINE_BACKLOG.md Phase 5 for the upstream lift plan.
+ *
+ * Closes #59 (H-035). Pairs with Phase 1.{2,3,4} of the backlog.
+ *
+ * Exports:
+ *   - SCHEMA_A, SCHEMA_B, SCHEMA_C, SCHEMA_UNKNOWN  : string constants
+ *   - detectSchema(parsed) → 'A' | 'B' | 'C' | 'unknown'
+ *   - parseLearningsFile(content, opts?) → { schema, eligible, warning?, parseError? }
+ *   - writeBackPromoted(content, schema, idsPromoted) → newContent
+ *
+ *   - parseSchemaA / parseSchemaB / parseSchemaC      (exported for unit tests)
+ *   - writeBackA / writeBackB / writeBackC            (exported for unit tests)
+ */
+const yaml = require('js-yaml');
+
+const SCHEMA_A = 'A';
+const SCHEMA_B = 'B';
+const SCHEMA_C = 'C';
+const SCHEMA_UNKNOWN = 'unknown';
+
+// LC-001 / #58 G2 partial: optional categorization. Per architect plan for
+// #58: schema extension only — auto-classifier deferred until OptionsFlow
+// E29-H worked examples land. All 3 categories are advisory; tooling
+// (audit-skills, audit-learnings) reads them when present.
+const LEARNING_CATEGORIES = Object.freeze({
+  APPLIED_EXISTING_RULE: 'applied-existing-rule',     // compliance evidence; reinforces an existing skill
+  DISCOVERED_NEW_PATTERN: 'discovered-new-pattern',   // promotion candidate; novel insight
+  EXCEPTION_WITH_RATIONALE: 'exception-with-rationale', // documented deviation from a rule
+});
+
+const VALID_CATEGORY_VALUES = Object.values(LEARNING_CATEGORIES);
+
+/**
+ * LC-001: validate optional category field. Returns the value if recognized,
+ * null if absent, throws if malformed.
+ */
+function validateCategory(value) {
+  if (value === null || value === undefined || value === '') return null;
+  if (typeof value !== 'string') {
+    throw new Error(`learning.category must be a string, got ${typeof value}`);
+  }
+  if (!VALID_CATEGORY_VALUES.includes(value)) {
+    throw new Error(`learning.category must be one of [${VALID_CATEGORY_VALUES.join(', ')}], got "${value}"`);
+  }
+  return value;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// detectSchema — reads only the top-level structure
+// ─────────────────────────────────────────────────────────────────────
+function detectSchema(parsed) {
+  if (parsed === null || parsed === undefined) return SCHEMA_UNKNOWN;
+  if (Array.isArray(parsed)) return SCHEMA_A;
+  if (typeof parsed !== 'object') return SCHEMA_UNKNOWN;
+  // Schema C wins on collision (both arrays present); caller emits warning.
+  if (Array.isArray(parsed.learnings)) return SCHEMA_C;
+  if (Array.isArray(parsed.enterprise_candidates)) return SCHEMA_B;
+  return SCHEMA_UNKNOWN;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// parseLearningsFile — entry point for the CLI shell
+// ─────────────────────────────────────────────────────────────────────
+//
+// Returns:
+//   { schema:    'A' | 'B' | 'C' | 'unknown',
+//     eligible:  NormalizedLearning[],
+//     warning?:  string,            // present on collision
+//     parseError?: Error }          // present if yaml.load threw
+//
+// NormalizedLearning shape (matches what hone-cli.js's downstream code
+// already expects — caller fills _file / _filePath / repo_name):
+//
+//   { id, story, enterprise_summary, skill_update, status,
+//     enterprise_candidate, _schema, _rawItemId? }
+//
+function parseLearningsFile(content, opts = {}) {
+  const fileLabel = opts.fileLabel || '<unknown>';
+  const includePromoted = opts.includePromoted || false;
+  let parsed;
+  try { parsed = yaml.load(content); }
+  catch (e) { return { schema: SCHEMA_UNKNOWN, eligible: [], parseError: e }; }
+
+  const schema = detectSchema(parsed);
+  if (schema === SCHEMA_UNKNOWN) return { schema, eligible: [] };
+
+  // Collision: dict with BOTH arrays. C wins, warn the caller.
+  let warning;
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      && Array.isArray(parsed.learnings)
+      && Array.isArray(parsed.enterprise_candidates)) {
+    warning = `${fileLabel}: both 'learnings' and 'enterprise_candidates' arrays present — using 'learnings' (Schema C); ignoring 'enterprise_candidates'.`;
+  }
+
+  // LC-001: validateCategory may throw on malformed enum value. Catch and
+  // surface as parseError rather than crashing the whole file walk.
+  try {
+    if (schema === SCHEMA_A) return { schema, eligible: parseSchemaA(parsed, includePromoted), warning };
+    if (schema === SCHEMA_B) return { schema, eligible: parseSchemaB(parsed, includePromoted), warning };
+    if (schema === SCHEMA_C) return { schema, eligible: parseSchemaC(parsed, includePromoted), warning };
+  } catch (e) {
+    return { schema, eligible: [], warning, parseError: e };
+  }
+  return { schema, eligible: [], warning };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Schema A — legacy list of items
+// ─────────────────────────────────────────────────────────────────────
+function parseSchemaA(items, includePromoted = false) {
+  return items
+    .filter(i => i && i.enterprise_candidate === true && (includePromoted || i.status === 'pending'))
+    .filter(i => i.enterprise_summary || i.summary)
+    .map(i => ({
+      id: i.id,
+      story: i.story,
+      enterprise_summary: i.enterprise_summary || i.summary,
+      skill_update: i.skill_update || null,
+      status: 'pending',
+      enterprise_candidate: true,
+      _schema: SCHEMA_A,
+      // LC-001: optional categorization fields (G2 partial). All optional;
+      // default null. validateCategory throws on malformed enum.
+      category: validateCategory(i.category),
+      referenced_skill: i.referenced_skill || null,
+      referenced_section: i.referenced_section || null,
+      evidence: Array.isArray(i.evidence) ? i.evidence : (i.evidence ? [i.evidence] : null),
+    }));
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Schema B — dict with enterprise_candidates
+// Eligibility: candidate_for non-null/undefined, status implicit 'pending'
+// (or explicit pending), non-empty `learning` body. Synthesizes id as
+// `${story_id}-${entry.id}` to match Schema A/C id-shape.
+// ─────────────────────────────────────────────────────────────────────
+function parseSchemaB(doc, includePromoted = false) {
+  const storyId = doc.story_id;
+  return (doc.enterprise_candidates || [])
+    .filter(c => c && c.candidate_for !== null && c.candidate_for !== undefined)
+    .filter(c => includePromoted || (c.status || 'pending') === 'pending')
+    .filter(c => c.learning && String(c.learning).trim().length > 0)
+    .map(c => ({
+      id: `${storyId}-${c.id}`,
+      story: storyId,
+      enterprise_summary: c.learning,
+      skill_update: c.candidate_for,
+      status: 'pending',
+      enterprise_candidate: true,
+      _schema: SCHEMA_B,
+      _rawItemId: c.id,
+      // LC-001: optional categorization fields. Schema B's pre-existing
+      // `candidate_for` already serves the role of referenced_skill, so
+      // we fall back to it when the explicit field is absent.
+      category: validateCategory(c.category),
+      referenced_skill: c.referenced_skill || c.candidate_for || null,
+      referenced_section: c.referenced_section || null,
+      evidence: Array.isArray(c.evidence) ? c.evidence : (c.evidence ? [c.evidence] : null),
+    }));
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Schema C — dict with learnings
+// Eligibility: per-item enterprise_candidate=true; status defaults to
+// top-level when per-item missing (so a story-level promoted/retracted
+// status skips the whole file). enterprise_summary is required —
+// local_summary is NEVER promoted (HONE-002 contract).
+// ─────────────────────────────────────────────────────────────────────
+function parseSchemaC(doc, includePromoted = false) {
+  const storyId = doc.story_id;
+  const topStatus = doc.status || 'pending';
+  return (doc.learnings || [])
+    .filter(l => l && l.enterprise_candidate === true)
+    .filter(l => includePromoted || (l.status || topStatus) === 'pending')
+    .filter(l => l.enterprise_summary && String(l.enterprise_summary).trim().length > 0)
+    .map(l => ({
+      id: l.id,
+      story: storyId,
+      enterprise_summary: l.enterprise_summary,
+      skill_update: null,                 // Schema C doesn't use skill_update yet
+      status: 'pending',
+      enterprise_candidate: true,
+      _schema: SCHEMA_C,
+      // LC-001: optional categorization fields (G2 partial).
+      category: validateCategory(l.category),
+      referenced_skill: l.referenced_skill || null,
+      referenced_section: l.referenced_section || null,
+      evidence: Array.isArray(l.evidence) ? l.evidence : (l.evidence ? [l.evidence] : null),
+    }));
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// writeBackPromoted — schema-aware idempotent regex rewrite
+//
+// All 3 schemas write per-item `status: promoted` because `hone retract`
+// at cli/hone-cli.js:1349 reads `entry?.status === 'retracted'` per-item.
+// Replacing per-item status with a top-level marker would break retract.
+// ─────────────────────────────────────────────────────────────────────
+function writeBackPromoted(content, schema, idsPromoted) {
+  if (!idsPromoted || idsPromoted.length === 0) return content;
+  if (schema === SCHEMA_A) return writeBackA(content, idsPromoted);
+  if (schema === SCHEMA_B) return writeBackB(content, idsPromoted);
+  if (schema === SCHEMA_C) return writeBackC(content, idsPromoted);
+  return content;
+}
+
+// Escape special regex characters from a YAML id (e.g. "H-001-L1").
+function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Schema A: per-item id-anchored regex replaces `pending` → `promoted`
+// next to each id. Mirrors the original cli/hone-cli.js:1295 behavior
+// exactly — no whitespace drift, byte-identical for adopters who haven't
+// migrated.
+function writeBackA(content, ids) {
+  for (const id of ids) {
+    const escaped = escapeRegex(id);
+    const idPattern = new RegExp(`(id:\\s*${escaped}[\\s\\S]*?status:\\s*)pending`, 'm');
+    if (idPattern.test(content)) {
+      content = content.replace(idPattern, '$1promoted');
+    }
+  }
+  return content;
+}
+
+// Schema B: ids look like "STORY-N" where N is the raw numeric per-item id.
+// Insert `    status: promoted` directly after the matched `- id: <N>` line.
+// Idempotent: skip insertion if any `status:` line already exists in the
+// item's block (between this id line and the next sibling id line).
+//
+// Line-by-line implementation (avoiding regex block-matching with \z, which
+// JS regex does not support — would silently match `z` literal instead).
+function writeBackB(content, idsPromoted) {
+  // Strip the story prefix to get the raw numeric ids: "TEST-B-1" → "1".
+  const rawIds = new Set();
+  for (const id of idsPromoted) {
+    const m = String(id).match(/^.*-(\d+)$/);
+    if (m) rawIds.add(m[1]);
+  }
+  if (rawIds.size === 0) return content;
+
+  return rewriteWithStatusInsertion(content, (line) => {
+    const m = line.match(/^( {2,})- id:\s*(\d+)\s*$/);
+    if (m && rawIds.has(m[2])) return { matched: true, indent: '    ' };
+    return { matched: false };
+  });
+}
+
+// Schema C: per-item id-anchored, scoped to entries under `learnings:`.
+// Insert `    status: promoted` directly after the matched `- id: <id>`
+// line. Idempotent: skip if any `status:` already exists in the item's
+// block. Top-level `status:` MUST NOT be touched — it's the story-level
+// status, separate from per-learning status.
+function writeBackC(content, ids) {
+  const idSet = new Set(ids.map(String));
+  if (idSet.size === 0) return content;
+
+  return rewriteWithStatusInsertion(content, (line) => {
+    const m = line.match(/^( {2,})- id:\s*(\S+)\s*$/);
+    if (m && idSet.has(m[2])) return { matched: true, indent: '    ' };
+    return { matched: false };
+  });
+}
+
+// Shared line-by-line worker for B + C. For each line that the matcher
+// flags, look ahead until the next sibling `  - id:` line (or end of file)
+// and check if any `status:` already exists there. If not, insert
+// `<indent>status: promoted` directly after the id line. Idempotent.
+function rewriteWithStatusInsertion(content, matcher) {
+  const lines = content.split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    out.push(line);
+    const r = matcher(line);
+    if (!r.matched) continue;
+
+    // Look ahead through this item's block to detect existing status.
+    let hasStatus = false;
+    for (let j = i + 1; j < lines.length; j++) {
+      const next = lines[j];
+      // End of block: next sibling id line at the same-or-lesser list indent.
+      if (/^ {2,}- id:/.test(next)) break;
+      // End of block: a non-indented (top-level) line means we've left the array.
+      if (/^\S/.test(next)) break;
+      if (/^ {4,}status:\s*\S/.test(next)) { hasStatus = true; break; }
+    }
+    if (!hasStatus) out.push(`${r.indent}status: promoted`);
+  }
+  return out.join('\n');
+}
+
+module.exports = {
+  SCHEMA_A,
+  SCHEMA_B,
+  SCHEMA_C,
+  SCHEMA_UNKNOWN,
+  detectSchema,
+  parseLearningsFile,
+  writeBackPromoted,
+  // LC-001 / #58 G2 partial: categorization API (advisory).
+  LEARNING_CATEGORIES,
+  VALID_CATEGORY_VALUES,
+  validateCategory,
+  // Exported for unit tests + future extension; not part of the stable
+  // public surface of the helper.
+  parseSchemaA,
+  parseSchemaB,
+  parseSchemaC,
+  writeBackA,
+  writeBackB,
+  writeBackC,
+};

package/lib/learnings-sync.js

@@ -0,0 +1,75 @@
+'use strict';
+/**
+ * learnings-sync.js — H-013 round-trip on promoted learnings.
+ *
+ * Pure helpers — no I/O. Caller (hone-cli.js sync command) reads the
+ * server response + writes back to local YAML files.
+ *
+ * Closes #22 client-side. Server endpoint
+ * `GET /promoted-learnings-report?repo=X` deferred to a follow-up
+ * (Hone-team operational concern).
+ *
+ * 9th instance of pure-helpers + thin-CLI-shell pattern in cli/lib/
+ * after H-018, H-035, H-009, H-008, H-021, H-061, H-010, H-015.
+ */
+
+// ─────────────────────────────────────────────────────────────────────
+// parseReportMarkdown — parse 4-column table rows
+// ─────────────────────────────────────────────────────────────────────
+//   Expected row shape: `| <id> | <summary> | <status> | <last-updated> |`
+//   Skips header row (cell text matches "ID" / "Summary" / "Status" /
+//   "Last updated") and separator row (cells are `---`).
+//   Returns [{id, summary, status, lastUpdated}]; [] on empty/unparseable.
+function parseReportMarkdown(text) {
+  if (typeof text !== 'string' || text.length === 0) return [];
+
+  const out = [];
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    // Must look like a table row: starts and ends with `|`, has ≥4 cells
+    if (!line.startsWith('|') || !line.endsWith('|')) continue;
+    const cells = line.slice(1, -1).split('|').map(c => c.trim());
+    if (cells.length < 4) continue;
+
+    // Skip separator rows (cells are dashes)
+    if (cells.every(c => /^[-:\s]+$/.test(c))) continue;
+
+    // Skip header row (heuristic: first cell is "ID" or contains "ID")
+    if (/^id$/i.test(cells[0])) continue;
+
+    out.push({
+      id: cells[0],
+      summary: cells[1],
+      status: cells[2].toLowerCase(),
+      lastUpdated: cells[3],
+    });
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// updateTopLevelStatus — surgical regex on TOP-LEVEL `status:` only
+// ─────────────────────────────────────────────────────────────────────
+//   Top-level = the `status:` line at column 0 (no leading whitespace).
+//   Per-item `status:` lines (indented under `learnings:`) are NOT touched.
+//   Returns {text, updated}:
+//     - updated=true if the top-level line was replaced
+//     - updated=false if no top-level `status:` exists (graceful)
+function updateTopLevelStatus(yamlText, newStatus) {
+  if (typeof yamlText !== 'string' || !newStatus) {
+    return { text: yamlText, updated: false };
+  }
+  // Match `status:` at start of line (no leading whitespace) — top-level only.
+  // The /m flag makes ^ match line starts; /\S/ guard ensures we capture the
+  // existing line even if it has trailing comment.
+  const re = /^status:\s*[^\n]*$/m;
+  if (!re.test(yamlText)) {
+    return { text: yamlText, updated: false };
+  }
+  return {
+    text: yamlText.replace(re, `status: ${newStatus}`),
+    updated: true,
+  };
+}
+
+module.exports = { parseReportMarkdown, updateTopLevelStatus };

package/lib/mcp-detect.js

@@ -0,0 +1,154 @@
+'use strict';
+/**
+ * mcp-detect.js — MCP server availability detection (HC-012).
+ *
+ * Pure helper with injected exec (same DI pattern as platform-detect.js).
+ * Checks whether an MCP server is available for the detected platform.
+ *
+ * SECURITY BOUNDARY:
+ *   - NEVER reads, stores, or transmits credentials
+ *   - Auth detection is observational: "does auth exist?" (yes/no)
+ *   - Output contains auth_method (HOW to auth) and auth_status
+ *     (authenticated/not/unknown), NEVER the credential itself
+ *   - Classifier: full-sdlc (security-implications + first-of-its-kind)
+ *
+ * Architecture: docs/architecture/platform-auto-discovery-v1.md (Tier 3)
+ */
+
+// ── Safe exec wrapper ──────────────────────────────────────────
+function safeExec(exec, cmd) {
+  try {
+    const result = exec(cmd);
+    return {
+      stdout: String(result.stdout || '').trim(),
+      exitCode: typeof result.exitCode === 'number' ? result.exitCode : 1,
+    };
+  } catch {
+    return { stdout: '', exitCode: 1 };
+  }
+}
+
+// ── Empty result ───────────────────────────────────────────────
+function emptyResult() {
+  return {
+    available: false,
+    server: null,
+    auth_method: null,
+    auth_status: 'unknown',
+    capabilities: [],
+    install_hint: null,
+    warnings: [],
+  };
+}
+
+// ── Salesforce MCP Detection ───────────────────────────────────
+function detectSalesforceMCP(exec) {
+  const result = emptyResult();
+
+  // 1. Check sf CLI installed
+  const sfVersion = safeExec(exec, 'sf --version');
+  if (sfVersion.exitCode !== 0) {
+    result.warnings.push('sf CLI not installed — MCP requires Salesforce CLI');
+    return result;
+  }
+
+  // 2. Check @salesforce/mcp installed
+  const mcpCheck = safeExec(exec, 'npm ls -g @salesforce/mcp');
+  const mcpInstalled = mcpCheck.exitCode === 0 && mcpCheck.stdout.includes('@salesforce/mcp');
+
+  if (mcpInstalled) {
+    result.server = '@salesforce/mcp';
+  } else {
+    result.install_hint = 'npm install -g @salesforce/mcp';
+  }
+
+  // 3. Check auth status (observational — NEVER extract tokens)
+  const authCheck = safeExec(exec, 'sf auth:list --json');
+  if (authCheck.exitCode === 0) {
+    try {
+      const parsed = JSON.parse(authCheck.stdout);
+      const orgs = Array.isArray(parsed.result) ? parsed.result : [];
+      if (orgs.length > 0) {
+        result.auth_method = 'sf-cli';
+        result.auth_status = 'authenticated';
+      } else {
+        result.auth_status = 'not_authenticated';
+      }
+    } catch {
+      result.auth_status = 'unknown';
+      result.warnings.push('sf auth:list returned non-JSON output');
+    }
+  } else {
+    result.auth_status = 'unknown';
+  }
+
+  // 4. Compose availability: need all three
+  result.available = mcpInstalled && result.auth_status === 'authenticated';
+
+  if (result.available) {
+    result.capabilities = ['metadata', 'soql', 'schema', 'apex-test'];
+  }
+
+  return result;
+}
+
+// ── NetSuite MCP Detection ─────────────────────────────────────
+function detectNetSuiteMCP(exec) {
+  const result = emptyResult();
+
+  // 1. Check community MCP server (global or local)
+  const globalCheck = safeExec(exec, 'npm ls -g netsuite-mcp-server');
+  const globalInstalled = globalCheck.exitCode === 0 && globalCheck.stdout.includes('netsuite-mcp-server');
+
+  let localInstalled = false;
+  if (!globalInstalled) {
+    const localCheck = safeExec(exec, 'npm ls netsuite-mcp-server');
+    localInstalled = localCheck.exitCode === 0 && localCheck.stdout.includes('netsuite-mcp-server');
+  }
+
+  if (globalInstalled || localInstalled) {
+    result.server = 'netsuite-mcp-server';
+    result.available = true;
+    result.capabilities = ['suiteql', 'records', 'restlet'];
+    result.auth_method = 'env-var';
+    result.auth_status = 'unknown'; // can't verify without connecting
+  } else {
+    result.install_hint = 'npm install -g netsuite-mcp-server (community)';
+  }
+
+  return result;
+}
+
+// ── Main Entry Point ───────────────────────────────────────────
+/**
+ * Detect MCP server availability for a platform.
+ *
+ * @param {object} opts
+ * @param {string} opts.platform - 'salesforce' | 'netsuite'
+ * @param {string} opts.repoRoot - reserved
+ * @param {(cmd: string) => {stdout: string, exitCode: number}} opts.exec - injected shell
+ * @returns {{ available, server, auth_method, auth_status, capabilities, install_hint, warnings }}
+ */
+function detectMCPServer(opts = {}) {
+  const { platform, exec } = opts;
+
+  if (typeof exec !== 'function') {
+    const result = emptyResult();
+    result.warnings.push('exec callback not provided');
+    return result;
+  }
+
+  try {
+    switch (platform) {
+      case 'salesforce': return detectSalesforceMCP(exec);
+      case 'netsuite':   return detectNetSuiteMCP(exec);
+      default: return emptyResult();
+    }
+  } catch (e) {
+    const result = emptyResult();
+    result.warnings.push(`MCP detection error: ${e.message}`);
+    return result;
+  }
+}
+
+module.exports = { detectMCPServer };