@axplusb/kepler 1.0.10 → 2.0.2

package/src/ui/dock.mjs

@@ -0,0 +1,88 @@
+/**
+ * Keyboard dock — Mission Control (PRD-055 §5.4).
+ *
+ * Maps each orbit to the dock hint shown on the second line of the status
+ * bar. Pure data so tests, the status bar, and `/help` stay in sync.
+ *
+ *   import { dockForOrbit } from './dock.mjs';
+ *   const hints = dockForOrbit(orbit);          // → [{ key, label }, ...]
+ *   const text  = renderDock(hints, paint);     // → ANSI-styled single line
+ */
+
+import { ORBITS } from '../state/orbit.mjs';
+import { paint, width } from './palette.mjs';
+import { term } from './term.mjs';
+
+const DEFAULT = [
+  { key: 'Enter', label: 'send'     },
+  { key: '/',     label: 'commands' },
+  { key: '?',     label: 'help'     },
+];
+
+const HINTS = {
+  [ORBITS.IDLE]: DEFAULT,
+  [ORBITS.DISCOVERY]: DEFAULT,
+
+  [ORBITS.PLANNING]: [
+    { key: 'p',   label: 'pause'      },
+    { key: 'Esc', label: 'interrupt'  },
+    { key: '?',   label: 'why'        },
+  ],
+
+  [ORBITS.EXECUTION]: [
+    { key: 'd',   label: 'last diff'  },
+    { key: 'p',   label: 'pause'      },
+    { key: 'Esc', label: 'interrupt'  },
+  ],
+
+  [ORBITS.ALIGNMENT]: [
+    { key: 'd',   label: 'last result' },
+    { key: '?',   label: 'explain'    },
+  ],
+
+  [ORBITS.AWAITING]: [
+    { key: 'Enter', label: 'approve' },
+    { key: 'e',     label: 'edit'    },
+    { key: 'r',     label: 're-plan' },
+    { key: 'n',     label: 'reject'  },
+    { key: '?',     label: 'why'     },
+  ],
+
+  [ORBITS.PAUSED]: [
+    { key: 'r',   label: 'resume'    },
+    { key: 'Esc', label: 'cancel'    },
+    { key: 'q',   label: 'quit'      },
+  ],
+};
+
+/**
+ * Return the array of hints for the given orbit.
+ * Falls back to the default dock for unknown orbits so the bar is never empty.
+ */
+export function dockForOrbit(orbit) {
+  return HINTS[orbit] || DEFAULT;
+}
+
+/**
+ * Render a hint list to an ANSI-styled line that fits within `maxWidth`
+ * visible characters. Drops trailing entries when they don't fit, never
+ * mid-hint truncates.
+ */
+export function renderDock(hints, maxWidth = term().columns - 2) {
+  if (!Array.isArray(hints) || hints.length === 0) return '';
+  const parts = [];
+  let used = 0;
+  for (const h of hints) {
+    const piece = `[${h.key}] ${h.label}`;
+    const sep = parts.length ? '  ' : '';
+    const cost = width(sep) + width(piece);
+    if (used + cost > maxWidth) break;
+    parts.push(sep + paintHint(h));
+    used += cost;
+  }
+  return parts.join('');
+}
+
+function paintHint(h) {
+  return paint.text.dim('[') + paint.brand.data(h.key) + paint.text.dim('] ' + h.label);
+}

package/src/ui/icons.mjs

@@ -0,0 +1,164 @@
+/**
+ * Brand icon registry — Mission Control (PRD-055 §4.2).
+ *
+ * Every CLI surface that prints a tool, phase, or status uses these icons.
+ * Each icon has a Unicode form and an ASCII fallback used when the terminal
+ * advertises no Unicode support (older Windows shells, locked-down CI).
+ *
+ *   import { icons, icon } from './icons.mjs';
+ *   process.stdout.write(`${icons.subAgent} explore  ${icons.pass} pass`);
+ *
+ * Or by token (for data-driven tool display):
+ *
+ *   icon('shell')        // ⚙️
+ *   icon('edit_file')    // 🛠️
+ */
+
+import { term } from './term.mjs';
+
+// ── Canonical icons ──────────────────────────────────────────────────────
+
+// Note: cannot Object.freeze() this — it is the target of a Proxy whose
+// `get` returns a rendered string instead of the raw record, which violates
+// the Proxy invariant for frozen targets.
+const ICONS = ({
+  // Brand
+  brand:     { utf: '✦',  ascii: '*'  },
+  orbit:     { utf: '◯',  ascii: 'O'  },
+
+  // Tool families
+  subAgent:  { utf: '🛰️', ascii: '~>' }, // explore, plan, verify, debug, refactor
+  search:    { utf: '🔭', ascii: '?'  }, // search_code, grep, read_file, list_files
+  write:     { utf: '🛠️', ascii: '+'  }, // write_file, edit_file, write_project
+  shell:     { utf: '⚙️', ascii: '$'  }, // shell, run_tests, validators
+  network:   { utf: '🌐', ascii: '@'  }, // WebFetch, MCP network calls
+
+  // State
+  pass:      { utf: '✅', ascii: 'OK' },
+  warn:      { utf: '⚠️', ascii: '!'  },
+  fail:      { utf: '❌', ascii: 'X'  },
+  pending:   { utf: '◔',  ascii: '.'  },
+
+  // Workflow
+  approve:   { utf: '✔',  ascii: 'Y'  },
+  reject:    { utf: '✘',  ascii: 'N'  },
+  pause:     { utf: '⏸',  ascii: '||' },
+  resume:    { utf: '▶',  ascii: '>'  },
+});
+
+// Internal table that the lookup functions consult directly. This stays
+// frozen because we never expose it through a Proxy.
+const ICON_RECORDS = Object.freeze({ ...ICONS });
+
+// ── Tool → icon mapping ──────────────────────────────────────────────────
+// One source of truth so tool display, status bar, and mission report
+// agree. Unknown tools fall through to a generic "tool" icon.
+
+const TOOL_ICON = Object.freeze({
+  // Sub-agents
+  explore:           'subAgent',
+  plan:              'subAgent',
+  verify:            'subAgent',
+  debug:             'subAgent',
+  refactor:          'subAgent',
+
+  // Read / search
+  read_file:         'search',
+  read_files:        'search',
+  search_code:       'search',
+  search_files:      'search',
+  grep:              'search',
+  list_files:        'search',
+  analyze_code:      'search',
+  get_file_info:     'search',
+  git_diff:          'search',
+  git_status:        'search',
+  get_project_overview: 'search',
+
+  // Write / edit
+  write_file:        'write',
+  write_project:     'write',
+  edit_file:         'write',
+  delete_file:       'write',
+
+  // Shell / validate
+  shell:             'shell',
+  run_tests:         'shell',
+  validate_build:    'shell',
+  validate_file:     'shell',
+  validate_structure:'shell',
+  lint_check:        'shell',
+
+  // Network
+  WebFetch:          'network',
+  fetch_url:         'network',
+});
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function render(spec) {
+  if (!spec) return '';
+  return term().unicode ? spec.utf : spec.ascii;
+}
+
+/**
+ * Resolve an icon by name (e.g. `icons.subAgent`). Always safe — returns
+ * the ASCII fallback when the terminal cannot render Unicode.
+ *
+ * Implemented as a Proxy over a plain object (intentionally not frozen, see
+ * the comment above ICONS) so callers can write `icons.pass` directly.
+ */
+export const icons = new Proxy({}, {
+  get(_target, prop) {
+    if (typeof prop !== 'string') return undefined;
+    return render(ICON_RECORDS[prop]);
+  },
+  has(_target, prop) {
+    return typeof prop === 'string' && prop in ICON_RECORDS;
+  },
+  ownKeys() {
+    return Object.keys(ICON_RECORDS);
+  },
+  getOwnPropertyDescriptor(_target, prop) {
+    if (typeof prop !== 'string' || !(prop in ICON_RECORDS)) return undefined;
+    return { configurable: true, enumerable: true, value: render(ICON_RECORDS[prop]) };
+  },
+});
+
+/**
+ * Resolve the icon for a tool name. Falls back to a generic tool icon
+ * (`◇`) when the tool is unknown to the registry — this is intentional so
+ * unmapped MCP tools and user-defined tools still render with the same
+ * visual rhythm.
+ */
+export function icon(toolName) {
+  if (!toolName) return '';
+  const key = TOOL_ICON[toolName];
+  if (key) return render(ICON_RECORDS[key]);
+
+  // MCP tools often arrive as "mcp__server__tool" — strip the prefix and
+  // try again before falling back to the generic glyph.
+  if (toolName.startsWith('mcp')) {
+    const cleaned = toolName.replace(/^mcp[_-]+/, '').split(/[_-]+/)[0];
+    const fallback = TOOL_ICON[cleaned];
+    if (fallback) return render(ICON_RECORDS[fallback]);
+  }
+
+  return term().unicode ? '◇' : '*';
+}
+
+/**
+ * Tool family (one of: subAgent, search, write, shell, network, other).
+ * Used by tier classification and color choice in the tool card renderer.
+ */
+export function toolFamily(toolName) {
+  return TOOL_ICON[toolName] || 'other';
+}
+
+/**
+ * Lower-level lookup for callers that want to know whether a name is in
+ * the registry (e.g. risk classification fall-throughs).
+ */
+export function hasIcon(name) {
+  return name in ICON_RECORDS;
+}

package/src/ui/mission-report.mjs

@@ -0,0 +1,264 @@
+/**
+ * Mission report — Mission Control (PRD-055 §11).
+ *
+ * Replaces the trailing "Done" message at the end of a session with a
+ * structured summary:
+ *
+ *   ───────────────────────────────────────────────────
+ *   ✅ MISSION ACCOMPLISHED · Fix JWT expiration bug
+ *   ───────────────────────────────────────────────────
+ *   📂 Files       auth.py, tests/test_auth.py
+ *   🛠️ Tools       read(4)  edit(2)  shell(1)  test(1)
+ *   🛰️ Sub-agents  explore(1)  plan(1) · saved ≈ $0.08
+ *   💰 Cost        $0.14    ⏱  Time  2m 18s
+ *   ✅ Health      24/24 tests pass
+ *   ───────────────────────────────────────────────────
+ *
+ *   Next:  /commit   /pr   /undo   /report
+ *
+ * Failure variant (PRD §11.1) uses ❌ MISSION HELD and lists blockers.
+ *
+ * `renderMissionReport(state)` returns the ANSI block; `toMarkdown(state)`
+ * returns the plain-markdown version saved by `/report`.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { paint, width as visibleWidth } from './palette.mjs';
+import { icons } from './icons.mjs';
+import { toolFamily } from './icons.mjs';
+
+const WIDTH = 56;
+
+// ── Public API ─────────────────────────────────────────────────────────
+
+/**
+ * Render the ANSI mission-report block.
+ *
+ * @param {object} state
+ *   task         — string (the user's prompt for this session)
+ *   success      — boolean (overall outcome)
+ *   filesChanged — string[]
+ *   toolCounts   — { [tool]: count } or array of {tool}
+ *   subAgents    — array of { type, costUsd?, tokens? } or { explore:1, plan:1 }
+ *   costUsd      — number
+ *   durationS    — number
+ *   testsPass    — { passed: number, total: number } | null
+ *   blockers     — string[] (for failure variant)
+ *   nextActions  — string[] (slash-command hints)
+ */
+export function renderMissionReport(state) {
+  const success = state.success !== false;
+  const lines = [];
+  const rule  = paint.text.dim('─'.repeat(WIDTH));
+
+  const titleIcon = success ? paint.state.success('✅') : paint.state.danger('❌');
+  const titleText = success ? 'MISSION ACCOMPLISHED' : 'MISSION HELD';
+  const titleAccent = success ? paint.state.success : paint.state.danger;
+  const headerTask = state.task ? paint.text.dim(' · ') + paint.text.primary(truncate(state.task, 60)) : '';
+
+  lines.push('');
+  lines.push(rule);
+  lines.push(`${titleIcon} ${paint.bold(titleAccent(titleText))}${headerTask}`);
+  lines.push(rule);
+
+  if (Array.isArray(state.filesChanged) && state.filesChanged.length) {
+    lines.push(row('📂', 'Files',      formatFiles(state.filesChanged)));
+  }
+
+  const toolSummary = formatToolCounts(state.toolCounts);
+  if (toolSummary) {
+    lines.push(row(icons.write, 'Tools', toolSummary));
+  }
+
+  if (state.subAgents) {
+    const subSummary = formatSubAgents(state.subAgents);
+    if (subSummary) lines.push(row(icons.subAgent, 'Sub-agents', subSummary));
+  }
+
+  // Cost + time on one row.
+  const cost = state.costUsd != null ? paint.brand.data(formatCost(state.costUsd)) : '';
+  const time = state.durationS != null ? paint.brand.data(formatDuration(state.durationS)) : '';
+  if (cost || time) {
+    const segments = [];
+    if (cost) segments.push(`${paint.text.dim('💰 Cost')}        ${cost}`);
+    if (time) segments.push(`${paint.text.dim('⏱  Time')}  ${time}`);
+    lines.push('  ' + segments.join('    '));
+  }
+
+  // Test health.
+  if (state.testsPass && typeof state.testsPass.total === 'number' && state.testsPass.total > 0) {
+    const { passed = 0, total = 0 } = state.testsPass;
+    const allGreen = passed === total;
+    const icon = allGreen ? paint.state.success('✅') : paint.state.danger('❌');
+    const text = allGreen
+      ? `${passed}/${total} tests pass`
+      : `${passed}/${total} tests pass · ${paint.state.danger((total - passed) + ' failing')}`;
+    lines.push(row(icon, allGreen ? 'Health' : 'Tests', text, /*alreadyIcon*/ true));
+  }
+
+  lines.push(rule);
+
+  if (!success && Array.isArray(state.blockers) && state.blockers.length) {
+    lines.push('');
+    lines.push('  ' + paint.bold(paint.state.danger('Blocked by:')));
+    for (const b of state.blockers.slice(0, 6)) {
+      lines.push('    ' + paint.text.dim('•') + ' ' + paint.text.primary(truncate(b, WIDTH * 2)));
+    }
+    if (state.blockers.length > 6) {
+      lines.push('    ' + paint.text.dim(`… ${state.blockers.length - 6} more`));
+    }
+  }
+
+  if (Array.isArray(state.nextActions) && state.nextActions.length) {
+    lines.push('');
+    const next = state.nextActions.map(a => paint.brand.data(a)).join(paint.text.dim('   '));
+    lines.push('  ' + paint.text.dim('Next:  ') + next);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Same content as renderMissionReport, but as plain markdown so callers
+ * can persist it under `.kepler/reports/`.
+ */
+export function toMarkdown(state) {
+  const success = state.success !== false;
+  const out = [];
+  out.push(`# ${success ? '✅ Mission Accomplished' : '❌ Mission Held'}${state.task ? ' — ' + state.task : ''}`);
+  out.push('');
+  if (Array.isArray(state.filesChanged) && state.filesChanged.length) {
+    out.push('**Files**: ' + state.filesChanged.join(', '));
+  }
+  const toolSummary = stripAnsi(formatToolCounts(state.toolCounts) || '');
+  if (toolSummary) out.push('**Tools**: ' + toolSummary);
+  if (state.subAgents) {
+    const sub = stripAnsi(formatSubAgents(state.subAgents) || '');
+    if (sub) out.push('**Sub-agents**: ' + sub);
+  }
+  if (state.costUsd != null) out.push('**Cost**: ' + stripAnsi(formatCost(state.costUsd)));
+  if (state.durationS != null) out.push('**Time**: ' + formatDuration(state.durationS));
+  if (state.testsPass) {
+    const { passed = 0, total = 0 } = state.testsPass;
+    out.push(`**Tests**: ${passed}/${total} ${passed === total ? 'pass' : 'pass · ' + (total - passed) + ' failing'}`);
+  }
+  if (!success && Array.isArray(state.blockers) && state.blockers.length) {
+    out.push('');
+    out.push('## Blocked by');
+    for (const b of state.blockers) out.push('- ' + b);
+  }
+  if (Array.isArray(state.nextActions) && state.nextActions.length) {
+    out.push('');
+    out.push('**Next**: ' + state.nextActions.join('  '));
+  }
+  out.push('');
+  return out.join('\n');
+}
+
+/**
+ * Save a markdown copy of the report to `.kepler/reports/<timestamp>.md`
+ * inside the working directory. Returns the absolute path.
+ */
+export function saveReport(state, { cwd = process.cwd(), timestamp } = {}) {
+  const dir = path.join(cwd, '.kepler', 'reports');
+  fs.mkdirSync(dir, { recursive: true });
+  const stamp = timestamp || new Date().toISOString().replace(/[:.]/g, '-');
+  const out = path.join(dir, `${stamp}.md`);
+  fs.writeFileSync(out, toMarkdown(state));
+  return out;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+function row(icon, label, value, alreadyIcon = false) {
+  const i = alreadyIcon ? icon : icon;
+  const labelText = paint.text.dim(label.padEnd(11));
+  return `  ${i} ${labelText} ${value}`;
+}
+
+function formatFiles(files) {
+  const shortened = files.map(f => paint.text.primary(path.basename(f)));
+  if (shortened.length <= 4) return shortened.join(paint.text.dim(', '));
+  return shortened.slice(0, 4).join(paint.text.dim(', ')) + paint.text.dim(`, +${files.length - 4} more`);
+}
+
+/**
+ * Render `read(4)  edit(2)  shell(1)  test(1)` from a counts object/array.
+ * Buckets by tool family so the line stays compact.
+ */
+function formatToolCounts(counts) {
+  if (!counts) return '';
+  const entries = Array.isArray(counts)
+    ? counts
+    : Object.entries(counts).map(([tool, n]) => ({ tool, count: n }));
+  if (!entries.length) return '';
+
+  const buckets = { read: 0, edit: 0, shell: 0, test: 0, other: 0 };
+  for (const { tool, count } of entries) {
+    const c = Number(count) || 0;
+    if (!c) continue;
+    const fam = toolFamily(tool);
+    if (tool === 'run_tests' || tool === 'validate_build') buckets.test += c;
+    else if (fam === 'write') buckets.edit += c;
+    else if (fam === 'shell') buckets.shell += c;
+    else if (fam === 'search') buckets.read += c;
+    else buckets.other += c;
+  }
+  const parts = [];
+  if (buckets.read)  parts.push(`${paint.brand.data('read')}(${buckets.read})`);
+  if (buckets.edit)  parts.push(`${paint.brand.primary('edit')}(${buckets.edit})`);
+  if (buckets.shell) parts.push(`${paint.state.warn('shell')}(${buckets.shell})`);
+  if (buckets.test)  parts.push(`${paint.state.success('test')}(${buckets.test})`);
+  if (buckets.other) parts.push(`${paint.text.muted('tool')}(${buckets.other})`);
+  return parts.join(paint.text.dim('  '));
+}
+
+function formatSubAgents(subAgents) {
+  // Accepts either a flat counts object { explore: 1, plan: 1, savedUsd: 0.08 }
+  // or an array of { type, costUsd, tokens }.
+  if (!subAgents) return '';
+  let counts = {};
+  let savedUsd = 0;
+  if (Array.isArray(subAgents)) {
+    for (const s of subAgents) {
+      counts[s.type] = (counts[s.type] || 0) + 1;
+      if (typeof s.savedUsd === 'number') savedUsd += s.savedUsd;
+    }
+  } else {
+    counts = { ...subAgents };
+    savedUsd = subAgents.savedUsd || 0;
+    delete counts.savedUsd;
+  }
+  const entries = Object.entries(counts).filter(([, n]) => Number(n) > 0);
+  if (!entries.length) return '';
+  const list = entries.map(([type, n]) => `${paint.brand.data(type)}(${n})`).join(paint.text.dim('  '));
+  if (savedUsd > 0) {
+    return list + paint.text.dim(` · saved ≈ ${formatCost(savedUsd)}`);
+  }
+  return list;
+}
+
+function formatCost(usd) {
+  if (typeof usd !== 'number' || !Number.isFinite(usd)) return '$0.00';
+  if (usd < 0.01) return `$${usd.toFixed(4)}`;
+  return `$${usd.toFixed(2)}`;
+}
+
+function formatDuration(s) {
+  if (typeof s !== 'number' || !Number.isFinite(s)) return '0s';
+  if (s < 60)  return `${s.toFixed(1)}s`;
+  const m = Math.floor(s / 60);
+  const rem = Math.round(s - m * 60);
+  return `${m}m ${rem}s`;
+}
+
+function truncate(s, n) {
+  const str = String(s || '');
+  return str.length <= n ? str : str.slice(0, n - 1) + '…';
+}
+
+function stripAnsi(s) {
+  return String(s || '').replace(/\x1b\[[0-9;]*m/g, '');
+}