agentboss 0.1.0

package/server/llm/project-advice.js

@@ -0,0 +1,491 @@
+/**
+ * High-level entry point for project-level AI advice generation.
+ *
+ * This is the cross-session counterpart of server/llm/advice.js:
+ * given a project + time window, assemble all per-session llm_advice
+ * payloads under that project, feed them to the LLM, and persist the
+ * second-pass summary into project_advice.
+ *
+ * Pipeline:
+ *   1. settings gate          — reuses enable_llm_judge (same toggle)
+ *   2. resolve sessions       — query unified_session by project + window
+ *   3. load per-session advice — pull cached llm_advice for each, skip
+ *                                  sessions that don't have one yet
+ *   4. cache check            — project_advice keyed by (project, scope,
+ *                                  windowFrom, windowTo) — fresh if
+ *                                  version matches AND the set of
+ *                                  session_ids hasn't changed
+ *   5. CLI detection          — opencode > claude
+ *   6. assemble + truncate    — see project-advice-prompt.js
+ *   7. runJudge under withSlot — 90 s timeout, JSON parsing, sentinel
+ *   8. persist                — UPSERT into project_advice
+ *
+ * Mirrors advice.js's failure-as-data convention: returns `{ ok:false,
+ * reason }` for normal-path failures instead of throwing.
+ *
+ * @author Felix
+ */
+
+'use strict';
+
+const {
+  detectAvailableCli,
+  runJudge,
+  withSlot,
+} = require('./cli-runner');
+const {
+  PROJECT_ADVICE_PROMPT_VERSION,
+  buildProjectAdvicePrompt,
+  truncateContext,
+  annotateContext,
+} = require('./project-advice-prompt');
+const { loadAdvice } = require('./advice');
+const {
+  queryAll,
+  queryOne,
+} = require('../db/queries');
+const { saveDb } = require('../db/connection');
+const { canonicalProject } = require('../utils/project');
+
+// ---------------------------------------------------------------------------
+//  Settings gate (shared toggle with judge / session advice)
+// ---------------------------------------------------------------------------
+
+let _settingsCache = null;
+let _settingsCacheAt = 0;
+const SETTINGS_TTL_MS = 10_000;
+
+function getSettings(db) {
+  const now = Date.now();
+  if (_settingsCache && now - _settingsCacheAt < SETTINGS_TTL_MS) {
+    return _settingsCache;
+  }
+  const rows = db.exec(
+    "SELECT key, value FROM user_settings WHERE key = 'enable_llm_judge'"
+  );
+  let enable = false;
+  if (rows[0]) {
+    for (const [, v] of rows[0].values) {
+      enable = String(v) === '1' || String(v).toLowerCase() === 'true';
+    }
+  }
+  _settingsCache = { enable_llm_judge: enable };
+  _settingsCacheAt = now;
+  return _settingsCache;
+}
+
+function invalidateProjectAdviceSettingsCache() {
+  _settingsCache = null;
+}
+
+// ---------------------------------------------------------------------------
+//  Session resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve all sessions belonging to a project within the window.  The
+ * project key is matched against the canonical form of unified_session.project
+ * — we LOAD candidates by a broad prefix-match LIKE clause and then
+ * canonicalise + exact-compare in JS, because storing the raw path means
+ * "C:/foo" and "C//foo" don't match via SQL alone.
+ *
+ * Returns rows sorted by started_at desc (newest first) so truncation
+ * keeps the most recent context.
+ */
+function resolveProjectSessions(db, projectKey, windowFrom, windowTo) {
+  // Use a broad LIKE so we don't miss path variants — final filter is JS-side.
+  // The canonical key has no trailing slash so we also accept the raw form +/.
+  const rough = canonicalProject(projectKey);
+  const stem = rough.replace(/[:/\\]/g, '%'); // very loose, JS filter is the gate
+
+  let sql = `
+    SELECT id, title, model, date, started_at, cost_usd, message_count,
+           error_count, project, parent_session_id, agent_type
+      FROM unified_session
+     WHERE project LIKE ?
+  `;
+  const params = [`%${stem}%`];
+  if (windowFrom && windowTo) {
+    sql += ' AND date BETWEEN ? AND ?';
+    params.push(windowFrom, windowTo);
+  }
+  sql += ' ORDER BY started_at DESC';
+  const rows = queryAll(db, sql, params);
+
+  return rows.filter((r) => canonicalProject(r.project) === rough);
+}
+
+/**
+ * For each session row, load the cached per-session llm_advice payload.
+ * Sessions without a cached advice are still returned (with advice=null)
+ * so the caller can count "how many of N still need session-level analysis".
+ *
+ * `parentSessionId` is forwarded so callers that want to hide subagents
+ * from the rendered session list can filter without re-querying.
+ */
+function attachSessionAdvice(db, rows) {
+  return rows.map((r) => {
+    const advice = loadAdvice(db, r.id);
+    return {
+      id: r.id,
+      title: r.title || '',
+      model: r.model || '',
+      date: r.date || '',
+      cost: r.cost_usd || 0,
+      msgCount: r.message_count || 0,
+      errorCount: r.error_count || 0,
+      parentSessionId: r.parent_session_id || null,
+      agentType:       r.agent_type        || null,
+      advice,                       // may be null
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+//  Cache load / store
+// ---------------------------------------------------------------------------
+
+function loadProjectAdvice(db, project, scope, windowFrom, windowTo) {
+  const row = queryOne(
+    db,
+    `SELECT * FROM project_advice
+      WHERE project = ? AND scope = ? AND window_from = ? AND window_to = ?`,
+    [project, scope, windowFrom || '', windowTo || '']
+  );
+  if (!row) return null;
+  let payload = null;
+  try { payload = row.llm_advice ? JSON.parse(row.llm_advice) : null; }
+  catch { payload = null; }
+  let sessionIds = [];
+  try { sessionIds = row.session_ids ? JSON.parse(row.session_ids) : []; }
+  catch { sessionIds = []; }
+  return {
+    project: row.project,
+    scope: row.scope,
+    windowFrom: row.window_from,
+    windowTo: row.window_to,
+    sessionCount: row.session_count || 0,
+    sessionIds,
+    v: row.v,
+    cli: row.cli,
+    cachedAt: row.cached_at,
+    payload,
+  };
+}
+
+function storeProjectAdvice(db, key, payload, meta) {
+  const json = JSON.stringify(payload);
+  const sessionIdsJson = JSON.stringify(meta.sessionIds || []);
+  const existing = queryOne(
+    db,
+    `SELECT 1 FROM project_advice
+      WHERE project = ? AND scope = ? AND window_from = ? AND window_to = ?`,
+    [key.project, key.scope, key.windowFrom, key.windowTo]
+  );
+  if (existing) {
+    db.run(
+      `UPDATE project_advice
+          SET session_count = ?, session_ids = ?, llm_advice = ?,
+              v = ?, cli = ?, cached_at = ?
+        WHERE project = ? AND scope = ? AND window_from = ? AND window_to = ?`,
+      [
+        meta.sessionCount, sessionIdsJson, json,
+        PROJECT_ADVICE_PROMPT_VERSION, meta.cli, new Date().toISOString(),
+        key.project, key.scope, key.windowFrom, key.windowTo,
+      ]
+    );
+  } else {
+    db.run(
+      `INSERT INTO project_advice
+         (project, scope, window_from, window_to, session_count, session_ids,
+          llm_advice, v, cli, cached_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        key.project, key.scope, key.windowFrom, key.windowTo,
+        meta.sessionCount, sessionIdsJson, json,
+        PROJECT_ADVICE_PROMPT_VERSION, meta.cli, new Date().toISOString(),
+      ]
+    );
+  }
+  try { saveDb(); } catch { /* noop */ }
+}
+
+/**
+ * Return a compact index of every cached project_advice row for this
+ * project — no payloads, just window keys + metadata.  The UI uses this
+ * to (a) pick a default window that actually has a cache, and (b) mark
+ * which tabs already have results.
+ *
+ * @param {object} db
+ * @param {string} project  canonical project path
+ * @returns {Array<{ scope, windowFrom, windowTo, sessionCount, v, cachedAt }>}
+ */
+function listProjectAdviceCaches(db, project) {
+  const rows = queryAll(
+    db,
+    `SELECT scope, window_from, window_to, session_count, v, cached_at
+       FROM project_advice
+      WHERE project = ?
+      ORDER BY cached_at DESC`,
+    [project]
+  );
+  return rows.map((r) => ({
+    scope:        r.scope,
+    windowFrom:   r.window_from,
+    windowTo:     r.window_to,
+    sessionCount: r.session_count || 0,
+    v:            r.v,
+    cachedAt:     r.cached_at,
+  }));
+}
+
+/** Fresh = same prompt version AND same set of session_ids. */
+function isCacheFresh(cached, currentIds) {
+  if (!cached || !cached.payload) return false;
+  if (cached.v !== PROJECT_ADVICE_PROMPT_VERSION) return false;
+  if ((cached.sessionIds || []).length !== currentIds.length) return false;
+  const a = [...cached.sessionIds].sort();
+  const b = [...currentIds].sort();
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+//  Stats aggregation
+// ---------------------------------------------------------------------------
+
+function summariseStats(db, sessions) {
+  let totalCost = 0;
+  let totalTokens = 0;
+  let totalErrors = 0;
+  let totalActiveMinutes = 0;
+  for (const s of sessions) {
+    totalCost += Number(s.cost) || 0;
+    totalErrors += Number(s.errorCount) || 0;
+  }
+  // Pull token / active_minute totals in one shot — we don't keep them on the
+  // already-trimmed session row to avoid loading bytes we won't use.
+  const ids = sessions.map((s) => s.id);
+  if (ids.length) {
+    const placeholders = ids.map(() => '?').join(',');
+    const row = queryOne(
+      db,
+      `SELECT SUM(COALESCE(tokens_input, 0) + COALESCE(tokens_output, 0)
+                + COALESCE(tokens_reasoning, 0))  AS tokens,
+              SUM(COALESCE(active_minutes, 0))    AS active_minutes
+         FROM unified_session
+        WHERE id IN (${placeholders})`,
+      ids
+    );
+    if (row) {
+      totalTokens = Number(row.tokens) || 0;
+      totalActiveMinutes = Number(row.active_minutes) || 0;
+    }
+  }
+  return {
+    sessionCount: sessions.length,
+    totalCost,
+    totalTokens,
+    totalErrors,
+    totalActiveMinutes,
+  };
+}
+
+// ---------------------------------------------------------------------------
+//  Public: generateProjectAdvice
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve sessions and (optionally) generate cross-session advice.
+ *
+ * Required opts:
+ *   - project    (string)              raw or canonical path
+ *   - scope      ('daily'|'weekly'|'all')
+ *   - windowFrom (YYYY-MM-DD, optional when scope='all')
+ *   - windowTo   (YYYY-MM-DD, optional when scope='all')
+ *
+ * Optional opts:
+ *   - force      (boolean, default false) bypass cache
+ *
+ * @returns {Promise<
+ *   { ok: true, data: { project, scope, windowFrom, windowTo, payload,
+ *                       sessionCount, sessionsWithAdvice, missingAdvice,
+ *                       cachedAt, fromCache },
+ *     payload?: object }
+ * | { ok: false, reason: string, error?: string }
+ * >}
+ */
+async function generateProjectAdvice(db, opts = {}) {
+  const force = opts.force === true;
+  const log = (...a) => {
+    if (process.env.ABOSS_ADVICE_DEBUG === '1') {
+      console.error('[project-advice]', opts.project, opts.scope, ...a);
+    }
+  };
+
+  try {
+    const project = canonicalProject(opts.project || '');
+    const scope = opts.scope || 'all';
+    const windowFrom = scope === 'all' ? '' : (opts.windowFrom || '');
+    const windowTo   = scope === 'all' ? '' : (opts.windowTo   || '');
+
+    if (!project) return { ok: false, reason: 'no-project' };
+    if (scope !== 'all' && (!windowFrom || !windowTo)) {
+      return { ok: false, reason: 'no-window' };
+    }
+
+    // 1. settings gate
+    const settings = getSettings(db);
+    if (!settings.enable_llm_judge) return { ok: false, reason: 'llm-disabled' };
+
+    // 2. resolve sessions
+    const raw = resolveProjectSessions(db, project, windowFrom, windowTo);
+    if (raw.length === 0) return { ok: false, reason: 'no-sessions' };
+
+    // 3. attach per-session advice; only keep ones that already have advice.
+    const enriched = attachSessionAdvice(db, raw);
+    const withAdvice = enriched.filter((s) => s.advice && s.advice.categories);
+    const missing = enriched.length - withAdvice.length;
+    if (withAdvice.length === 0) {
+      return {
+        ok: false,
+        reason: 'no-session-advice',
+        meta: { sessionCount: enriched.length, missingAdvice: missing },
+      };
+    }
+
+    const key = { project, scope, windowFrom, windowTo };
+    const currentIds = withAdvice.map((s) => s.id);
+
+    // 4. cache check
+    const cached = loadProjectAdvice(db, project, scope, windowFrom, windowTo);
+    if (!force && isCacheFresh(cached, currentIds)) {
+      log('cache hit');
+      return {
+        ok: true,
+        data: {
+          ...key,
+          payload: cached.payload,
+          sessionCount: cached.sessionCount,
+          sessionsWithAdvice: withAdvice.length,
+          missingAdvice: missing,
+          cachedAt: cached.cachedAt,
+          fromCache: true,
+        },
+      };
+    }
+
+    // 5. CLI detection
+    const cli = await detectAvailableCli();
+    if (!cli) return { ok: false, reason: 'no-cli' };
+
+    // 6. assemble + truncate
+    const stats = summariseStats(db, withAdvice);
+    const ctx = annotateContext({
+      project, scope, windowFrom, windowTo,
+      stats,
+      sessions: withAdvice,
+    });
+    const trimmed = truncateContext(ctx);
+    const prompt = buildProjectAdvicePrompt(trimmed);
+    log('spawning', cli.name, 'prompt bytes=', prompt.length,
+        'truncated=', trimmed.truncated, 'sessions=', trimmed.sessions.length);
+
+    // 7. run
+    const result = await withSlot(() => runJudge({ prompt, timeoutMs: 120_000 }));
+    if (!result.ok) {
+      return { ok: false, reason: result.reason, error: result.error };
+    }
+
+    const payload = normaliseProjectPayload(result.data, {
+      truncated: trimmed.truncated,
+      omittedSessions: trimmed.omittedSessions,
+    });
+
+    // 8. persist
+    storeProjectAdvice(db, key, payload, {
+      sessionCount: withAdvice.length,
+      sessionIds: currentIds,
+      cli: result.cli,
+    });
+
+    return {
+      ok: true,
+      data: {
+        ...key,
+        payload,
+        sessionCount: withAdvice.length,
+        sessionsWithAdvice: withAdvice.length,
+        missingAdvice: missing,
+        cachedAt: new Date().toISOString(),
+        fromCache: false,
+      },
+    };
+  } catch (err) {
+    log('internal', err && err.message);
+    return { ok: false, reason: 'internal', error: err && err.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Payload normalisation (mirrors session normaliseAdvicePayload)
+// ---------------------------------------------------------------------------
+
+const ALL_CATEGORIES = ['cost', 'accuracy', 'context', 'skills', 'workflow'];
+const ALL_SEVERITIES = ['high', 'medium', 'low'];
+const ALL_EXECUTORS  = ['opencode', 'claude', 'manual'];
+const ALL_CWD_HINTS  = ['project_root'];
+
+function normaliseProjectPayload(raw, meta) {
+  const cats = (raw && typeof raw.categories === 'object' && raw.categories) || {};
+  const categories = {};
+  for (const key of ALL_CATEGORIES) {
+    const arr = Array.isArray(cats[key]) ? cats[key] : [];
+    categories[key] = arr.map(normaliseItem).filter((it) => it && it.evidence);
+  }
+  const patternsRaw = Array.isArray(raw && raw.crossSessionPatterns) ? raw.crossSessionPatterns : [];
+  const crossSessionPatterns = patternsRaw
+    .filter((p) => typeof p === 'string')
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .slice(0, 5);
+  return {
+    v: PROJECT_ADVICE_PROMPT_VERSION,
+    cachedAt: new Date().toISOString(),
+    truncated: meta.truncated || false,
+    omittedSessions: meta.omittedSessions || 0,
+    summary: typeof raw?.summary === 'string' ? raw.summary : '',
+    crossSessionPatterns,
+    categories,
+    rationale: typeof raw?.rationale === 'string' ? raw.rationale : '',
+  };
+}
+
+function normaliseItem(it) {
+  if (!it || typeof it !== 'object') return null;
+  const severity = ALL_SEVERITIES.includes(it.severity) ? it.severity : 'low';
+  let executor = ALL_EXECUTORS.includes(it.executor) ? it.executor : 'manual';
+  let actionable = it.actionable === true;
+  const cwd_hint = ALL_CWD_HINTS.includes(it.cwd_hint) ? it.cwd_hint : 'project_root';
+  if (executor === 'manual') actionable = false;
+  if (actionable && executor === 'manual') executor = 'opencode';
+  return {
+    severity,
+    title:    typeof it.title === 'string'    ? it.title.trim()    : '',
+    why:      typeof it.why === 'string'      ? it.why.trim()      : '',
+    action:   typeof it.action === 'string'   ? it.action.trim()   : '',
+    evidence: typeof it.evidence === 'string' ? it.evidence.trim() : '',
+    actionable,
+    executor,
+    cwd_hint,
+  };
+}
+
+module.exports = {
+  generateProjectAdvice,
+  loadProjectAdvice,
+  listProjectAdviceCaches,
+  resolveProjectSessions,
+  attachSessionAdvice,
+  invalidateProjectAdviceSettingsCache,
+};

package/server/llm/session-analyzer.js

@@ -0,0 +1,122 @@
+/**
+ * Unified per-session LLM analyzer — ONE CLI call that returns both the
+ * v2.1 capability scores and the collaboration advice.
+ *
+ * Supersedes the two separate calls (judge.judgeSession + advice.generateAdvice).
+ * Pipeline:
+ *   1. settings gate (enable_llm_judge)
+ *   2. assemble context (reuses advice.assembleContext) + real difficulty
+ *   3. cache check in session_analysis.llm_judge_v2 (v + msgCount)
+ *   4. truncate + build combined prompt
+ *   5. runJudge under withSlot (90 s)
+ *   6. return { scores, advice, rationale, v, msgCount, cli, cachedAt } | null
+ *
+ * Returns null on disabled / no-cli / failure so callers fall back to rules.
+ *
+ * @author Felix
+ */
+
+'use strict';
+
+const { detectAvailableCli, runJudge, withSlot } = require('./cli-runner');
+const {
+  ANALYSIS_PROMPT_VERSION,
+  buildSessionAnalysisPrompt,
+  truncateContext,
+} = require('./analysis-prompt');
+const { assembleContext } = require('./advice');
+const { classifySession } = require('../analysis/difficulty');
+const { queryOne } = require('../db/queries');
+
+// ---------------------------------------------------------------------------
+//  Settings gate (mirrors judge.js / advice.js; tiny TTL cache)
+// ---------------------------------------------------------------------------
+
+let _settingsCache = null;
+let _settingsCacheAt = 0;
+const SETTINGS_TTL_MS = 10_000;
+
+function getSettings(db) {
+  const now = Date.now();
+  if (_settingsCache && now - _settingsCacheAt < SETTINGS_TTL_MS) return _settingsCache;
+  const rows = db.exec("SELECT value FROM user_settings WHERE key = 'enable_llm_judge'");
+  let enable = false;
+  if (rows[0]) {
+    for (const [v] of rows[0].values) {
+      enable = String(v) === '1' || String(v).toLowerCase() === 'true';
+    }
+  }
+  _settingsCache = { enable_llm_judge: enable };
+  _settingsCacheAt = now;
+  return _settingsCache;
+}
+
+/** Drop the settings cache (called by PUT /api/settings). */
+function invalidateAnalyzerSettingsCache() { _settingsCache = null; }
+
+// ---------------------------------------------------------------------------
+//  Cache
+// ---------------------------------------------------------------------------
+
+function loadCache(db, sessionId) {
+  const row = queryOne(db, 'SELECT llm_judge_v2 FROM session_analysis WHERE session_id = ?', [sessionId]);
+  if (!row || !row.llm_judge_v2) return null;
+  try { return JSON.parse(row.llm_judge_v2); }
+  catch { return null; }
+}
+
+// ---------------------------------------------------------------------------
+//  Public: analyzeSessionLLM
+// ---------------------------------------------------------------------------
+
+/**
+ * Run (or return cached) the combined scores+advice analysis for a session.
+ *
+ * @param {object}  db
+ * @param {object}  session   unified_session row
+ * @param {object} [opts]     { force?: boolean }
+ * @returns {Promise<{scores:object, advice:object, rationale?:string,
+ *   v:number, msgCount:number, cli:string, cachedAt:string} | null>}
+ */
+async function analyzeSessionLLM(db, session, opts = {}) {
+  const settings = getSettings(db);
+  if (!settings.enable_llm_judge) return null;
+
+  const ctxFull = assembleContext(db, session.id);
+  if (!ctxFull) return null;
+  const msgCount = ctxFull.messages.length;
+
+  if (opts.force !== true) {
+    const cache = loadCache(db, session.id);
+    if (cache && cache.v === ANALYSIS_PROMPT_VERSION && cache.msgCount === msgCount && cache.scores) {
+      return cache;
+    }
+  }
+
+  const cli = await detectAvailableCli();
+  if (!cli) return null;
+
+  // Surface the REAL difficulty to the rubric (advice.assembleContext nulls
+  // it out on purpose; scoring needs it).
+  const difficulty = classifySession(session).bucket;
+  ctxFull.session.difficulty = difficulty;
+
+  const ctx = truncateContext(ctxFull);
+  ctx.session = ctxFull.session; // truncateContext shallow-copies; keep difficulty
+  const prompt = buildSessionAnalysisPrompt(ctx);
+
+  const result = await withSlot(() => runJudge({ prompt, timeoutMs: 90_000 }));
+  if (!result.ok || !result.data || !result.data.scores) return null;
+
+  return {
+    scores: result.data.scores,
+    advice: result.data.advice || null,
+    rationale: typeof result.data.rationale === 'string' ? result.data.rationale : '',
+    v: ANALYSIS_PROMPT_VERSION,
+    msgCount,
+    cli: result.cli,
+    cachedAt: new Date().toISOString(),
+  };
+}
+
+module.exports = { analyzeSessionLLM, invalidateAnalyzerSettingsCache };

package/server/utils/project.js

@@ -0,0 +1,80 @@
+/**
+ * Project path helpers shared across API + analysis layers.
+ *
+ * The canonical form is the single source of truth for "is this the same
+ * project?" comparisons.  Always normalise before using a path as a map
+ * key, as a DB primary key, or before deciding two rows belong together.
+ *
+ * Lifted out of server/api/overview.js so the yesterday-report builder
+ * and the project-detail page can collapse paths the same way.
+ *
+ * @author Felix
+ */
+
+/**
+ * Normalise a project path so equivalent paths collapse to one row.
+ *
+ * Real-world data has two issues that need cleaning before grouping:
+ *   1. OpenCode sometimes records Windows drives as "C//felix/code/X"
+ *      (the colon got dropped); we treat that as "C:/felix/code/X".
+ *   2. Trailing slashes and back-slash / forward-slash mixing also
+ *      produce duplicates.
+ *
+ * The returned canonical form uses forward slashes only, no trailing
+ * slash, and re-inserts the colon after a single-letter drive prefix.
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+function canonicalProject(p) {
+  if (!p) return p;
+  let s = String(p).replace(/\\/g, '/');             // back-slash → forward
+  s = s.replace(/^([A-Za-z])\/\//, '$1://');          // "C//foo" → "C://foo"
+  s = s.replace(/^([A-Za-z]):?\/+/, '$1:/');          // collapse "C:////" or "C/" → "C:/"
+  s = s.replace(/\/+/g, '/');                         // collapse internal "//"
+  s = s.replace(/\/+$/, '');                          // strip trailing slash
+  return s;
+}
+
+/**
+ * Reshape and de-duplicate top-project rows.  Groups by canonical project
+ * key, sums all numeric fields, then sorts by cost desc and applies the
+ * requested limit.
+ *
+ * @param {Object[]} rows  raw SQL rows (already aggregated by raw project)
+ * @param {number}   limit
+ * @returns {Object[]}
+ */
+function mapTopProjects(rows, limit) {
+  const byKey = new Map();
+  for (const r of rows) {
+    const key = canonicalProject(r.project);
+    if (!byKey.has(key)) {
+      byKey.set(key, {
+        project:   key,
+        sessions:  0,
+        cost:      0,
+        additions: 0,
+        deletions: 0,
+        files:     0,
+      });
+    }
+    const acc = byKey.get(key);
+    acc.sessions  += r.sessions      || 0;
+    acc.cost      += r.cost          || 0;
+    acc.additions += r.additions     || 0;
+    acc.deletions += r.deletions     || 0;
+    acc.files     += r.files         || 0;
+  }
+  const merged = Array.from(byKey.values()).map((r) => ({
+    ...r,
+    cost: Math.round(r.cost * 10000) / 10000,
+  }));
+  merged.sort((a, b) => (b.cost - a.cost) || (b.sessions - a.sessions));
+  return merged.slice(0, limit);
+}
+
+module.exports = {
+  canonicalProject,
+  mapTopProjects,
+};