@nemus-cli/nemus 0.5.0 → 0.9.0

package/src/utils/editor.ts

@@ -0,0 +1,48 @@
+import { spawnSync } from 'child_process';
+
+/**
+ * Resolve the user's preferred editor as an argv array. Honors `$VISUAL` then
+ * `$EDITOR` (the long-standing Unix convention — `VISUAL` wins for full-screen
+ * editors), falling back to `notepad` on Windows and `vi` elsewhere. The env
+ * value may include flags (e.g. `code --wait`, `emacs -nw`), so it's split on
+ * whitespace into a command + args. Pure + unit-tested.
+ */
+export function resolveEditor(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string[] {
+  const raw = (env.VISUAL || env.EDITOR || '').trim();
+  if (raw) return raw.split(/\s+/);
+  return platform === 'win32' ? ['notepad'] : ['vi'];
+}
+
+export interface EditorResult {
+  ok: boolean;
+  /** Editor argv[0] that was launched. */
+  editor: string;
+  /** Process exit code, when the editor ran and exited normally. */
+  code?: number;
+  /** Populated when the editor couldn't be launched at all. */
+  error?: string;
+}
+
+/**
+ * Open `file` in the resolved editor, inheriting the terminal so the editor is
+ * interactive. Returns a structured result rather than throwing so the caller
+ * controls messaging/exit. `spawn` is injected for tests.
+ */
+export function openInEditor(
+  file: string,
+  deps: { spawn?: typeof spawnSync; env?: NodeJS.ProcessEnv; platform?: NodeJS.Platform } = {},
+): EditorResult {
+  const spawn = deps.spawn ?? spawnSync;
+  const [cmd, ...args] = resolveEditor(deps.env, deps.platform);
+  const res = spawn(cmd, [...args, file], { stdio: 'inherit' });
+  if (res.error) {
+    const err = res.error as NodeJS.ErrnoException;
+    const reason = err.code === 'ENOENT' ? `editor "${cmd}" not found` : err.message;
+    return { ok: false, editor: cmd, error: reason };
+  }
+  const code = typeof res.status === 'number' ? res.status : 1;
+  return { ok: code === 0, editor: cmd, code };
+}

package/src/utils/reflect.test.ts

@@ -1,6 +1,7 @@
-import { describe, it, expect } from 'vitest';
-import { distillTranscript, parseReflectionReport, classifyAgentsMd, isCorrectionPrompt, saveReflectionReport } from './reflect';
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { distillTranscript, parseReflectionReport, classifyAgentsMd, isCorrectionPrompt, saveReflectionReport, severityCounts, severitySummary, renderReportMarkdown, groupRecommendations, listSavedReports, loadSavedReport, findSavedMatches, SavedReport, ReflectionReport, Recommendation } from './reflect';
 import * as fs from 'fs/promises';
+import * as os from 'os';
 import * as path from 'path';
 
 const J = (o: unknown) => JSON.stringify(o);
@@ -124,3 +125,129 @@ describe('parseReflectionReport', () => {
     expect(parseReflectionReport({ recommendations: 'nope' })).toEqual({ summary: '', recommendations: [] });
   });
 });
+
+describe('severityCounts / severitySummary', () => {
+  const recs = (ps: Array<'high' | 'medium' | 'low'>) =>
+    ps.map((priority) => ({ kind: 'other' as const, title: 't', detail: 'd', priority }));
+
+  it('counts by priority', () => {
+    expect(severityCounts(recs(['high', 'high', 'low']))).toEqual({ high: 2, medium: 0, low: 1 });
+  });
+  it('summary omits empty buckets and is empty for none', () => {
+    expect(severitySummary(recs(['high', 'medium', 'medium']))).toBe('1 high · 2 medium');
+    expect(severitySummary([])).toBe('');
+  });
+});
+
+describe('renderReportMarkdown', () => {
+  const report: ReflectionReport = {
+    summary: 'Overall fine.',
+    recommendations: [
+      { kind: 'skill', title: 'Add deploy skill', detail: 'manual steps', priority: 'high', target: 'acme/api', example: 'name: deploy' },
+      { kind: 'context', title: 'Doc lint', detail: 'guessed', priority: 'medium' },
+    ],
+  };
+
+  it('groups by severity with a count line and headings', () => {
+    const md = renderReportMarkdown(report, { analyzed: 5, workspaces: 3, generatedAt: '2026-09-01T12:00:00Z' });
+    expect(md).toMatch(/^# Reflection/);
+    expect(md).toContain('_5 sessions across 3 workspaces · 2026-09-01T12:00:00Z_');
+    expect(md).toContain('**1 high · 1 medium**');
+    expect(md).toContain('### High priority');
+    expect(md).toContain('### Medium priority');
+    // high appears before medium
+    expect(md.indexOf('### High priority')).toBeLessThan(md.indexOf('### Medium priority'));
+    expect(md).toContain('- **[Skill] Add deploy skill** (`acme/api`)');
+    expect(md).toContain('- **[Context/AGENTS.md] Doc lint**');
+    expect(md.endsWith('\n')).toBe(true);
+  });
+
+  it('uses a single-workspace scope line', () => {
+    const md = renderReportMarkdown(report, { analyzed: 1, workspaces: 1, workspace: 'my-ws' });
+    expect(md).toContain('_workspace **my-ws**_');
+  });
+
+  it('escapes an example that itself contains a triple-backtick fence', () => {
+    const r: ReflectionReport = {
+      summary: '',
+      recommendations: [{ kind: 'other', title: 'x', detail: '', priority: 'low', example: 'a ```b``` c' }],
+    };
+    const md = renderReportMarkdown(r, { analyzed: 1, workspaces: 1 });
+    expect(md).toContain('````'); // fence longer than the inner run
+    expect(md).toContain('a ```b``` c');
+  });
+
+  it('renders a clean empty state', () => {
+    const md = renderReportMarkdown({ summary: 'All good.', recommendations: [] }, { analyzed: 2, workspaces: 2 });
+    expect(md).toContain('_No specific recommendations — looks solid._');
+    expect(md).not.toContain('### High');
+  });
+});
+
+describe('groupRecommendations', () => {
+  const mk = (kind: Recommendation['kind'], priority: Recommendation['priority'], title = 't'): Recommendation =>
+    ({ kind, title, detail: 'd', priority });
+
+  it('groups by priority (high→low), omitting empty groups', () => {
+    const groups = groupRecommendations([mk('skill', 'low'), mk('context', 'high')], 'priority');
+    expect(groups.map((g) => g.key)).toEqual(['high', 'low']); // no 'medium'
+    expect(groups[0].heading).toBe('High priority');
+  });
+
+  it('groups by kind in a fixed order, priority-sorted within a kind', () => {
+    const groups = groupRecommendations(
+      [mk('context', 'low'), mk('skill', 'low', 'a'), mk('skill', 'high', 'b')],
+      'kind',
+    );
+    expect(groups.map((g) => g.key)).toEqual(['skill', 'context']); // skill before context
+    expect(groups[0].recs.map((r) => r.title)).toEqual(['b', 'a']); // high before low within skill
+  });
+});
+
+describe('findSavedMatches (pure)', () => {
+  const mk = (id: string): SavedReport => ({ id, file: `${id}.json`, analyzed: 0, workspaces: 0, report: { summary: '', recommendations: [] } });
+  // newest-first list, as listSavedReports returns it
+  const all = [mk('2000-03'), mk('2000-02b'), mk('2000-02a'), mk('2000-01')];
+
+  it('empty / latest / exact', () => {
+    expect(findSavedMatches([], '2000')).toEqual([]);
+    expect(findSavedMatches(all)[0].id).toBe('2000-03'); // undefined -> newest
+    expect(findSavedMatches(all, 'latest')[0].id).toBe('2000-03');
+    expect(findSavedMatches(all, '2000-02a').map((r) => r.id)).toEqual(['2000-02a']); // exact wins
+  });
+  it('an ambiguous prefix returns every match, newest-first', () => {
+    expect(findSavedMatches(all, '2000-02').map((r) => r.id)).toEqual(['2000-02b', '2000-02a']);
+    expect(findSavedMatches(all, 'nope')).toEqual([]);
+  });
+});
+
+describe('listSavedReports / loadSavedReport (isolated temp dir)', () => {
+  let dir: string;
+  const idA = '2000-01-01T00-00-00-000Z-vitestA';
+  const idB = '2000-01-02T00-00-00-000Z-vitestB';
+
+  beforeAll(async () => {
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), 'nemus-reflect-test-'));
+    await fs.writeFile(path.join(dir, `${idA}.json`), JSON.stringify({ generatedAt: '2000-01-01T00:00:00.000Z', analyzed: 4, workspaces: 3, summary: 'old', recommendations: [{ kind: 'skill', title: 'x', detail: 'd', priority: 'high' }] }));
+    await fs.writeFile(path.join(dir, `${idB}.json`), JSON.stringify({ generatedAt: '2000-01-02T00:00:00.000Z', analyzed: 1, workspaces: 1, workspace: 'ws', summary: 'new', recommendations: [] }));
+    await fs.writeFile(path.join(dir, 'not-json.txt'), 'ignore me');
+    await fs.writeFile(path.join(dir, 'corrupt.json'), '{ not valid json');
+  });
+  afterAll(async () => {
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  it('lists newest-first, skipping non-json and corrupt files', async () => {
+    const all = await listSavedReports(dir);
+    expect(all.map((r) => r.id)).toEqual([idB, idA]); // exactly two, newer first
+    expect(all[0].workspace).toBe('ws');
+    expect(all[0].report.recommendations).toHaveLength(0);
+  });
+
+  it('loadSavedReport resolves latest, exact id, and prefix', async () => {
+    expect((await loadSavedReport('latest', dir))?.id).toBe(idB);
+    expect((await loadSavedReport(idA, dir))?.workspaces).toBe(3);
+    expect((await loadSavedReport('2000-01-02T00-00-00', dir))?.id).toBe(idB);
+    expect(await loadSavedReport('definitely-no-such-id-xyz', dir)).toBeNull();
+  });
+});

package/src/utils/reflect.ts

@@ -63,6 +63,134 @@ export interface ReflectionReport {
   recommendations: Recommendation[];
 }
 
+// ------------------------------------------------------------ report rendering
+
+export type Priority = Recommendation['priority'];
+
+/** Count recommendations by priority. */
+export function severityCounts(recs: Recommendation[]): Record<Priority, number> {
+  const counts: Record<Priority, number> = { high: 0, medium: 0, low: 0 };
+  for (const r of recs) counts[r.priority]++;
+  return counts;
+}
+
+/** "3 high · 2 medium · 1 low", omitting zero buckets; '' when there are none. */
+export function severitySummary(recs: Recommendation[]): string {
+  const c = severityCounts(recs);
+  return (['high', 'medium', 'low'] as Priority[])
+    .filter((p) => c[p] > 0)
+    .map((p) => `${c[p]} ${p}`)
+    .join(' · ');
+}
+
+export const KIND_LABEL: Record<RecommendationKind, string> = {
+  skill: 'Skill',
+  context: 'Context/AGENTS.md',
+  test: 'Test',
+  prompt: 'Prompt',
+  connectivity: 'Connectivity',
+  workflow: 'Workflow',
+  other: 'Other',
+};
+// Back-compat alias for existing references.
+const MD_KIND_LABEL = KIND_LABEL;
+
+export const PRIORITY_HEADING: Record<Priority, string> = {
+  high: 'High priority',
+  medium: 'Medium priority',
+  low: 'Low priority',
+};
+
+export type GroupBy = 'priority' | 'kind';
+
+const KIND_ORDER: RecommendationKind[] = ['skill', 'context', 'test', 'prompt', 'connectivity', 'workflow', 'other'];
+const PRIORITY_ORDER: Priority[] = ['high', 'medium', 'low'];
+const PRIORITY_RANK: Record<Priority, number> = { high: 0, medium: 1, low: 2 };
+
+export interface RecGroup {
+  key: string;
+  heading: string;
+  recs: Recommendation[];
+}
+
+/**
+ * Split recommendations into ordered, non-empty groups by either priority
+ * (high→low) or kind (a fixed, stable order). When grouping by kind, each
+ * group's recs are sorted high-priority first. Pure + unit-tested; shared by the
+ * Markdown renderer and the human printer so the two never diverge.
+ */
+export function groupRecommendations(recs: Recommendation[], groupBy: GroupBy): RecGroup[] {
+  if (groupBy === 'kind') {
+    return KIND_ORDER.map((k) => ({
+      key: k,
+      heading: KIND_LABEL[k],
+      recs: recs
+        .filter((r) => r.kind === k)
+        .sort((a, b) => PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority]),
+    })).filter((g) => g.recs.length > 0);
+  }
+  return PRIORITY_ORDER.map((p) => ({
+    key: p,
+    heading: PRIORITY_HEADING[p],
+    recs: recs.filter((r) => r.priority === p),
+  })).filter((g) => g.recs.length > 0);
+}
+
+/** A fenced code block whose fence is guaranteed longer than any backtick run
+ *  inside `body`, so the snippet can't break out of its own fence. */
+function fencedBlock(body: string): string {
+  const longest = Math.max(0, ...(body.match(/`+/g) ?? []).map((m) => m.length));
+  const fence = '`'.repeat(Math.max(3, longest + 1));
+  return `${fence}\n${body}\n${fence}`;
+}
+
+/**
+ * Render a reflection report as clean Markdown — for pasting into an issue/PR or
+ * saving alongside the JSON. Pure (no color, no I/O) so it's unit-tested.
+ * Recommendations are grouped by severity (high→low); each carries its kind,
+ * optional target, detail, and a fenced example.
+ */
+export function renderReportMarkdown(
+  report: ReflectionReport,
+  meta: { analyzed: number; workspaces: number; workspace?: string; generatedAt?: string },
+  groupBy: GroupBy = 'priority',
+): string {
+  const lines: string[] = ['# Reflection', ''];
+  const scope = meta.workspace
+    ? `workspace **${meta.workspace}**`
+    : `${meta.analyzed} session${meta.analyzed === 1 ? '' : 's'} across ${meta.workspaces} workspace${meta.workspaces === 1 ? '' : 's'}`;
+  const stamp = meta.generatedAt ? ` · ${meta.generatedAt}` : '';
+  lines.push(`_${scope}${stamp}_`, '');
+
+  if (report.summary.trim()) lines.push(report.summary.trim(), '');
+
+  if (report.recommendations.length === 0) {
+    lines.push('## Recommendations', '', '_No specific recommendations — looks solid._', '');
+    return lines.join('\n');
+  }
+
+  lines.push('## Recommendations', '', `**${severitySummary(report.recommendations)}**`, '');
+
+  for (const group of groupRecommendations(report.recommendations, groupBy)) {
+    lines.push(`### ${group.heading}`, '');
+    for (const r of group.recs) {
+      const target = r.target ? ` (\`${r.target}\`)` : '';
+      // Under a kind heading the [Kind] prefix is redundant; show a priority tag
+      // instead. Under a priority heading, show the kind.
+      const label = groupBy === 'kind' ? `_${r.priority}_ — ` : `[${KIND_LABEL[r.kind]}] `;
+      lines.push(`- **${label}${r.title}**${target}`);
+      if (r.detail.trim()) {
+        lines.push(...r.detail.trim().split('\n').map((l) => `  ${l}`));
+      }
+      if (r.example?.trim()) {
+        lines.push('', ...fencedBlock(r.example.trim()).split('\n').map((l) => `  ${l}`));
+      }
+      lines.push('');
+    }
+  }
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+
 // --------------------------------------------------------- transcript distill
 
 // Kept deliberately lean: the judge runs on the user's own (often local, slow)
@@ -455,3 +583,76 @@ export async function saveReflectionReport(
   await fs.writeFile(file, JSON.stringify({ generatedAt: new Date().toISOString(), ...meta, ...report }, null, 2));
   return file;
 }
+
+/** A saved report on disk, with its metadata and parsed report. */
+export interface SavedReport {
+  /** Basename without .json — the id used by `reflect show <id>`. */
+  id: string;
+  file: string;
+  generatedAt?: string;
+  analyzed: number;
+  workspaces: number;
+  workspace?: string;
+  report: ReflectionReport;
+}
+
+/**
+ * List saved reports under `~/.nemus/reflect/`, newest first (filenames start
+ * with an ISO timestamp, so a reverse name sort is chronological). Unreadable /
+ * unparseable files are skipped, not fatal. Returns [] if the dir is absent.
+ */
+export async function listSavedReports(dir: string = REFLECT_REPORTS_DIR): Promise<SavedReport[]> {
+  let names: string[];
+  try {
+    names = await fs.readdir(dir);
+  } catch {
+    return [];
+  }
+  const jsons = names.filter((n) => n.endsWith('.json')).sort().reverse();
+  const out: SavedReport[] = [];
+  for (const name of jsons) {
+    const file = path.join(dir, name);
+    try {
+      const raw = JSON.parse(await fs.readFile(file, 'utf-8'));
+      out.push({
+        id: name.replace(/\.json$/, ''),
+        file,
+        generatedAt: typeof raw.generatedAt === 'string' ? raw.generatedAt : undefined,
+        analyzed: typeof raw.analyzed === 'number' ? raw.analyzed : 0,
+        workspaces: typeof raw.workspaces === 'number' ? raw.workspaces : 0,
+        workspace: typeof raw.workspace === 'string' ? raw.workspace : undefined,
+        report: parseReflectionReport(raw),
+      });
+    } catch {
+      /* skip a corrupt/partial file */
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve a report reference against an (already newest-first) list. Returns ALL
+ * matches so a caller can detect ambiguity: `undefined`/`'latest'` -> the newest;
+ * an exact id -> that one; otherwise every id with the prefix (newest-first). An
+ * exact id always wins over prefixes, so an id can't be ambiguous with itself.
+ * Pure + unit-tested.
+ */
+export function findSavedMatches(all: SavedReport[], ref?: string): SavedReport[] {
+  if (all.length === 0) return [];
+  if (!ref || ref === 'latest') return [all[0]];
+  const exact = all.find((r) => r.id === ref);
+  if (exact) return [exact];
+  return all.filter((r) => r.id.startsWith(ref));
+}
+
+/**
+ * Load one saved report by id. `undefined`/`'latest'` returns the newest; an id
+ * is matched exactly, then as a prefix (newest match wins). Returns null when
+ * nothing matches. For ambiguity-aware callers, use findSavedMatches directly.
+ */
+export async function loadSavedReport(
+  ref?: string,
+  dir: string = REFLECT_REPORTS_DIR,
+): Promise<SavedReport | null> {
+  return findSavedMatches(await listSavedReports(dir), ref)[0] ?? null;
+}