Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
15.7 KB
Raw Blame
/**
 * `buildTodayDashboard(vault, opts)` - today operator surface (Task 4).
 *
 * Composes five independently-computed, live-derived sections into one
 * read-only envelope: due/overdue obligations, one-off pledges, open
 * loops, recent activity, and a totals rollup. Each section is built
 * from its own primitive - `listObligations`, `listPledges`,
 * `scanOpenLoops`, `buildActivityTimeline` over `buildTimelineIndex` -
 * and nothing here re-scans the vault a second time; `totals` is pure
 * arithmetic over the four already-built sections.
 *
 * Fault isolation: each section is computed inside its own try/catch. A
 * section whose builder throws contributes an explicit entry to the
 * envelope's `errors` array ({ section, message }) and falls back to a
 * well-formed empty shape for that section; the other sections still
 * compute and render normally. The rendered `## <Section>` block for a
 * failed section prints an explicit `- error: <message>` line instead of
 * silently looking like an empty-but-healthy section - an empty render
 * with no accompanying error would misrepresent a scan failure as "there
 * is simply nothing here".
 *
 * Determinism: every date-sensitive computation flows from `opts.now`;
 * nothing here reads the wall clock. The envelope, every section, and
 * every nested array are frozen.
 */

import { listObligations } from "./obligations.ts";
import { listPledges, type PledgeListItem } from "./pledges.ts";
import { BRAIN_OBLIGATIONS_REL } from "./path-constants.ts";
import { scanOpenLoops, type OpenLoopScan } from "./open-loops.ts";
import { isoSecond } from "./time.ts";
import { buildActivityTimeline, type ActivityTimeline } from "./temporal/activity-timeline.ts";
import { buildTimelineIndex } from "./temporal/build-index.ts";
import type { TemporalEvent, TimelineIndex } from "./temporal/types.ts";

/** Options accepted by {@link buildTodayDashboard}. */
export interface TodayDashboardOptions {
  /** Wall clock; every date/age computation derives from this. */
  readonly now: Date;
  /** Days of log history the recent-activity section windows over. Default 7. */
  readonly activityLookbackDays?: number;
  /** Max recent-activity entries to keep, newest first. Default 20. */
  readonly activityLimit?: number;
  /**
   * The form of one log event the caller may see, or `null` when it may
   * not see it at all. Applied to the recent-activity events before the
   * limit and the totals, so a withheld event moves neither. Omitted, every
   * event is shown as logged (the operator's own shell).
   */
  readonly eventAtReach?: (ev: TemporalEvent) => TemporalEvent | null;
  /**
   * Whether the caller may read a vault-relative path. Obligation pages,
   * pledge pages and open-loop notes it rejects are left out before the
   * totals, so they move no count. Omitted, every page is listed (the
   * operator's own shell).
   */
  readonly readable?: (rel: string) => boolean;
}

/** One obligation row surfaced on the dashboard. */
export interface TodayDashboardObligationItem {
  readonly slug: string;
  readonly title: string;
  /** True when next-due is strictly before today (UTC). */
  readonly overdue: boolean;
  /** Whole days until next-due; negative when overdue, zero when due today. */
  readonly daysUntilDue: number;
  readonly nextDue: string;
}

/** Obligations section: due-today / overdue first, via `listObligations`'s own sort. */
export interface TodayDashboardObligationsSection {
  readonly items: ReadonlyArray<TodayDashboardObligationItem>;
}

/** One pledge row surfaced on the dashboard (open pledges only). */
export interface TodayDashboardPledgeItem {
  readonly slug: string;
  readonly title: string;
  readonly due: string;
  /** True when due is strictly before today (UTC). */
  readonly overdue: boolean;
  /** Whole days until due; negative when overdue, zero when due today, null when undated. */
  readonly daysUntilDue: number | null;
}

/** Pledges section: earliest-due first, via `listPledges`'s own sort. */
export interface TodayDashboardPledgesSection {
  readonly items: ReadonlyArray<TodayDashboardPledgeItem>;
}

/** Deterministic counters derived from the other four sections. No second scan. */
export interface TodayDashboardTotals {
  readonly obligationsTotal: number;
  readonly obligationsOverdue: number;
  readonly obligationsDueToday: number;
  readonly pledgesTotal: number;
  readonly pledgesOverdue: number;
  readonly openLoopsCount: number;
  readonly recentActivityTotal: number;
  readonly scannedFiles: number;
}

/** The five independently-computed dashboard sections. */
export type TodayDashboardSectionName =
  | "obligations"
  | "pledges"
  | "openLoops"
  | "recentActivity"
  | "totals";

/** One per-section computation failure. */
export interface TodayDashboardSectionError {
  readonly section: TodayDashboardSectionName;
  readonly message: string;
}

/** Frozen envelope returned by {@link buildTodayDashboard}. */
export interface TodayDashboard {
  readonly obligations: TodayDashboardObligationsSection;
  readonly pledges: TodayDashboardPledgesSection;
  readonly openLoops: OpenLoopScan;
  readonly recentActivity: ActivityTimeline;
  readonly totals: TodayDashboardTotals;
  /** Per-section failures; empty when every section computed cleanly. */
  readonly errors: ReadonlyArray<TodayDashboardSectionError>;
  /** Rendered Markdown: `## Obligations`, `## Pledges`, `## Open loops`, `## Recent activity`, `## Totals`, in that order. */
  readonly text: string;
}

const DEFAULT_ACTIVITY_LOOKBACK_DAYS = 7;
const DEFAULT_ACTIVITY_LIMIT = 20;
const DAY_MS = 24 * 60 * 60 * 1000;

const EMPTY_OBLIGATIONS_SECTION: TodayDashboardObligationsSection = Object.freeze({
  items: Object.freeze([]) as ReadonlyArray<TodayDashboardObligationItem>,
});

const EMPTY_PLEDGES_SECTION: TodayDashboardPledgesSection = Object.freeze({
  items: Object.freeze([]) as ReadonlyArray<TodayDashboardPledgeItem>,
});

const EMPTY_OPEN_LOOP_SCAN: OpenLoopScan = Object.freeze({
  openLoops: Object.freeze([]),
  counts: Object.freeze({ openCount: 0, closedCount: 0, scannedFiles: 0 }),
  duplicates: Object.freeze([]),
  orphanCloses: Object.freeze([]),
});

const EMPTY_ACTIVITY_TIMELINE: ActivityTimeline = Object.freeze({
  entries: Object.freeze([]),
  bullets: Object.freeze([]),
  text: "",
  total: 0,
});

const EMPTY_TOTALS: TodayDashboardTotals = Object.freeze({
  obligationsTotal: 0,
  obligationsOverdue: 0,
  obligationsDueToday: 0,
  pledgesTotal: 0,
  pledgesOverdue: 0,
  openLoopsCount: 0,
  recentActivityTotal: 0,
  scannedFiles: 0,
});

/**
 * Validate the caller-supplied option knobs up front, before any section
 * runs. An invalid option is a programmer error, not a data-conditioned
 * partial failure - it is rejected outright rather than routed through
 * per-section fault isolation.
 */
function resolveWindowOptions(opts: TodayDashboardOptions): {
  readonly lookbackDays: number;
  readonly limit: number;
} {
  const lookbackDays = opts.activityLookbackDays ?? DEFAULT_ACTIVITY_LOOKBACK_DAYS;
  if (!Number.isInteger(lookbackDays) || lookbackDays < 0) {
    throw new Error(
      `buildTodayDashboard: activityLookbackDays must be a non-negative integer; got ${JSON.stringify(opts.activityLookbackDays)}`,
    );
  }
  const limit = opts.activityLimit ?? DEFAULT_ACTIVITY_LIMIT;
  if (!Number.isInteger(limit) || limit < 0) {
    throw new Error(
      `buildTodayDashboard: activityLimit must be a non-negative integer; got ${JSON.stringify(opts.activityLimit)}`,
    );
  }
  return { lookbackDays, limit };
}

/** Run one section's builder, recording a typed error and falling back to an empty shape on throw. */
function computeSection<T>(
  section: TodayDashboardSectionName,
  errors: TodayDashboardSectionError[],
  compute: () => T,
  fallback: T,
): T {
  try {
    return compute();
  } catch (err) {
    errors.push({ section, message: err instanceof Error ? err.message : String(err) });
    return fallback;
  }
}

function buildObligationsSection(
  vault: string,
  now: Date,
  readable: TodayDashboardOptions["readable"],
): TodayDashboardObligationsSection {
  const listed = listObligations(vault, { now });
  const shown =
    readable === undefined
      ? listed
      : listed.filter((o) => readable(`${BRAIN_OBLIGATIONS_REL}/${o.slug}.md`));
  const items = shown.map((o) =>
    Object.freeze({
      slug: o.slug,
      title: o.title,
      overdue: o.overdue,
      daysUntilDue: o.daysUntilDue,
      nextDue: o.nextDue,
    }),
  );
  return Object.freeze({ items: Object.freeze(items) });
}

/**
 * The pledges section reads the family through `listPledges`, which takes
 * the same readable predicate the obligations section filters with, so a
 * withheld page is dropped before anything counts it - identical to absent.
 */
function buildPledgesSection(
  vault: string,
  now: Date,
  readable: TodayDashboardOptions["readable"],
): TodayDashboardPledgesSection {
  const listed: ReadonlyArray<PledgeListItem> = listPledges(vault, {
    now,
    ...(readable === undefined ? {} : { readable }),
  });
  const items = listed.map((p) =>
    Object.freeze({
      slug: p.slug,
      title: p.title,
      due: p.due,
      overdue: p.overdue,
      daysUntilDue: p.daysUntilDue,
    }),
  );
  return Object.freeze({ items: Object.freeze(items) });
}

function buildRecentActivitySection(
  vault: string,
  now: Date,
  lookbackDays: number,
  limit: number,
  eventAtReach: TodayDashboardOptions["eventAtReach"],
): ActivityTimeline {
  const since = isoSecond(new Date(now.getTime() - lookbackDays * DAY_MS));
  const index = buildTimelineIndex(vault, { now, since });
  const shown = eventAtReach === undefined ? index : indexAtReach(index, eventAtReach);
  return buildActivityTimeline(shown, { now, since, limit });
}

/**
 * The index holding only the events the caller may see, each in its
 * visible form, regrouped so every lookup the timeline builder may take
 * agrees with the event list.
 */
function indexAtReach(
  index: TimelineIndex,
  eventAtReach: (ev: TemporalEvent) => TemporalEvent | null,
): TimelineIndex {
  const events = index.events.flatMap((ev) => eventAtReach(ev) ?? []);
  const group = <K>(
    key: (ev: TemporalEvent) => K | undefined,
  ): ReadonlyMap<K, ReadonlyArray<TemporalEvent>> => {
    const out = new Map<K, TemporalEvent[]>();
    for (const ev of events) {
      const k = key(ev);
      if (k === undefined) continue;
      const bucket = out.get(k);
      if (bucket === undefined) out.set(k, [ev]);
      else bucket.push(ev);
    }
    return out;
  };
  return Object.freeze({
    events: Object.freeze(events),
    eventsByKind: group((ev) => ev.kind),
    eventsByPrefId: group((ev) => ev.prefId),
    eventsByTopic: group((ev) => ev.topic),
    window: index.window,
  });
}

function computeTotals(
  obligations: TodayDashboardObligationsSection,
  pledges: TodayDashboardPledgesSection,
  openLoops: OpenLoopScan,
  recentActivity: ActivityTimeline,
): TodayDashboardTotals {
  let overdue = 0;
  let dueToday = 0;
  for (const item of obligations.items) {
    if (item.overdue) overdue++;
    else if (item.daysUntilDue === 0) dueToday++;
  }
  let pledgesOverdue = 0;
  for (const item of pledges.items) {
    if (item.overdue) pledgesOverdue++;
  }
  return Object.freeze({
    obligationsTotal: obligations.items.length,
    obligationsOverdue: overdue,
    obligationsDueToday: dueToday,
    pledgesTotal: pledges.items.length,
    pledgesOverdue,
    openLoopsCount: openLoops.counts.openCount,
    recentActivityTotal: recentActivity.total,
    scannedFiles: openLoops.counts.scannedFiles,
  });
}

function renderObligationLine(item: TodayDashboardObligationItem): string {
  const state = item.overdue
    ? `overdue by ${Math.abs(item.daysUntilDue)}d`
    : item.daysUntilDue === 0
      ? "due today"
      : `due in ${item.daysUntilDue}d`;
  return `- ${item.title} (slug: ${item.slug}) - next due ${item.nextDue} - ${state}`;
}

function renderPledgeLine(item: TodayDashboardPledgeItem): string {
  if (item.daysUntilDue === null) {
    return `- ${item.title} (slug: ${item.slug}) - undated`;
  }
  let state: string;
  if (item.overdue) state = `overdue by ${Math.abs(item.daysUntilDue)}d`;
  else if (item.daysUntilDue === 0) state = "due today";
  else state = `due in ${item.daysUntilDue}d`;
  return `- ${item.title} (slug: ${item.slug}) - due ${item.due} - ${state}`;
}

function renderOpenLoopLine(loop: OpenLoopScan["openLoops"][number]): string {
  return `- ${loop.text} (id: ${loop.id}) - ${loop.path}:${loop.line}`;
}

function renderSection(
  header: string,
  errorMessage: string | undefined,
  lines: ReadonlyArray<string>,
): string {
  if (errorMessage !== undefined) {
    return [header, `- error: ${errorMessage}`].join("\n");
  }
  return [header, ...(lines.length > 0 ? lines : ["(none)"])].join("\n");
}

function renderDashboardText(
  obligations: TodayDashboardObligationsSection,
  pledges: TodayDashboardPledgesSection,
  openLoops: OpenLoopScan,
  recentActivity: ActivityTimeline,
  totals: TodayDashboardTotals,
  errors: ReadonlyArray<TodayDashboardSectionError>,
): string {
  const errorBySection = new Map(errors.map((e) => [e.section, e.message] as const));

  const obligationsBlock = renderSection(
    "## Obligations",
    errorBySection.get("obligations"),
    obligations.items.map(renderObligationLine),
  );
  const pledgesBlock = renderSection(
    "## Pledges",
    errorBySection.get("pledges"),
    pledges.items.map(renderPledgeLine),
  );
  const openLoopsBlock = renderSection(
    "## Open loops",
    errorBySection.get("openLoops"),
    openLoops.openLoops.map(renderOpenLoopLine),
  );
  const recentActivityBlock = renderSection(
    "## Recent activity",
    errorBySection.get("recentActivity"),
    recentActivity.bullets,
  );
  const totalsBlock = renderSection("## Totals", errorBySection.get("totals"), [
    `Obligations: ${totals.obligationsTotal}`,
    `Overdue: ${totals.obligationsOverdue}`,
    `Due today: ${totals.obligationsDueToday}`,
    `Pledges: ${totals.pledgesTotal}`,
    `Pledges overdue: ${totals.pledgesOverdue}`,
    `Open loops: ${totals.openLoopsCount}`,
    `Recent activity: ${totals.recentActivityTotal}`,
    `Scanned files: ${totals.scannedFiles}`,
  ]);

  return [obligationsBlock, pledgesBlock, openLoopsBlock, recentActivityBlock, totalsBlock].join(
    "\n\n",
  );
}

/**
 * Build the today dashboard for a vault. Read-only; deterministic given
 * `opts.now`. Each of the five sections computes independently - a
 * section that throws is recorded in `errors` and rendered as an
 * explicit error line, the rest of the envelope still reflects a normal
 * computation.
 */
export function buildTodayDashboard(vault: string, opts: TodayDashboardOptions): TodayDashboard {
  const { lookbackDays, limit } = resolveWindowOptions(opts);
  const errors: TodayDashboardSectionError[] = [];

  const obligations = computeSection(
    "obligations",
    errors,
    () => buildObligationsSection(vault, opts.now, opts.readable),
    EMPTY_OBLIGATIONS_SECTION,
  );
  const pledges = computeSection(
    "pledges",
    errors,
    () => buildPledgesSection(vault, opts.now, opts.readable),
    EMPTY_PLEDGES_SECTION,
  );
  const openLoops = computeSection(
    "openLoops",
    errors,
    () => scanOpenLoops(vault, opts.readable === undefined ? {} : { readable: opts.readable }),
    EMPTY_OPEN_LOOP_SCAN,
  );
  const recentActivity = computeSection(
    "recentActivity",
    errors,
    () => buildRecentActivitySection(vault, opts.now, lookbackDays, limit, opts.eventAtReach),
    EMPTY_ACTIVITY_TIMELINE,
  );
  const totals = computeSection(
    "totals",
    errors,
    () => computeTotals(obligations, pledges, openLoops, recentActivity),
    EMPTY_TOTALS,
  );

  const text = renderDashboardText(obligations, pledges, openLoops, recentActivity, totals, errors);

  return Object.freeze({
    obligations,
    pledges,
    openLoops,
    recentActivity,
    totals,
    errors: Object.freeze(errors.slice()),
    text,
  });
}