Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

29.6 KB
Raw Blame
import {
  findGitRoot,
  gitUserEmail,
  projectFiles,
  readCommitFiles,
  readCommitSubjects,
} from "../git.js";
import { CliError, type Io } from "../io.js";
import { readSessionMessages, type SessionMessage, upgradeSessionIds } from "../messages.js";
import type { LineageNode, Session } from "../schema/session.js";
import { applyEvents, readEvents } from "../store/events.js";
import { resolveProjectRoot } from "../store/root.js";
import { loadAllSessions, loadProject } from "../store/stores.js";
import {
  attachThoughtTrailers,
  earliestSessionStart,
  readCommitAuthorEmail,
  readCommitThought,
  readThoughtTrailers,
} from "../thought.js";
import { buildFileHistory, type FileSourceSession } from "../view/files.js";
import { buildMessages } from "../view/lineage.js";
import type { ViewFile, ViewNode } from "../view/model.js";

/**
 * `cogit log` and `cogit show` (Story 8.10): the CLI's read verbs,
 * modelled on `git log` and `git show`. The agent is the main reader, so the
 * output is plain text by default and JSON on request; neither command writes.
 *
 * A message is addressed by its stable id (`h` plus 12 hex) or any unique prefix
 * of at least six hex characters after the `h`, or by `<sessionId-prefix>:mN`.
 */

/** One session as the map sees it: stable ids, replayed structure, message order. */
export interface EffectiveSession {
  session: Session;
  /** buildMessages output: labels, parents and links already normalised. */
  messages: ViewNode[];
  /**
   * The user messages with their stable ids and conversation text, or null when
   * neither the transcript nor the conversation store is readable. Search reads
   * this (Story 8.14); the read verbs do not need it.
   */
  turns: SessionMessage[] | null;
}

/** Every valid session of the project, with the ids and structure the map draws. */
export async function loadEffectiveSessions(root: string, io: Io): Promise<EffectiveSession[]> {
  const sessions = await loadAllSessions(root, io.warn);
  // The `Thought:` trailers git already holds (Story 9.4): a commit whose message
  // names a message belongs to it even when the agent's record left it out.
  const trailers = await readThoughtTrailers(root, {
    env: io.env,
    since: earliestSessionStart(sessions),
  });
  const loaded: EffectiveSession[] = [];
  for (const session of sessions) {
    // The transcript (or the conversation store) names old `m1` nodes and holds
    // the hash of each message; a session without either keeps its stored ids.
    const turns = await readSessionMessages(root, session.sessionId, io.env);
    const upgraded = turns ? upgradeSessionIds(session, turns) : session;
    const events = await readEvents(root, session.sessionId);
    const effective: Session = { ...upgraded, nodes: applyEvents(upgraded.nodes, events) };
    loaded.push({ session: effective, messages: buildMessages(effective.nodes), turns });
  }
  const withThoughts = attachThoughtTrailers(
    loaded.map((entry) => entry.session),
    trailers,
  );
  const out = loaded.map((entry, index) => {
    const session = withThoughts[index] as Session;
    return session === entry.session
      ? entry
      : { ...entry, session, messages: buildMessages(session.nodes) };
  });
  return out.sort(
    (a, b) =>
      a.session.startedAt.localeCompare(b.session.startedAt) ||
      a.session.sessionId.localeCompare(b.session.sessionId),
  );
}

/** Loads the project record, refusing an uninitialized or broken project. */
export async function openProject(dir: string): Promise<string> {
  const { root } = await resolveProjectRoot(dir);
  const project = await loadProject(root);
  if (!project.found) throw new CliError(`${root} is not initialized; run \`cogit init\` first`);
  if (!project.ok) throw new CliError(project.error);
  return root;
}

const pad = (value: number): string => String(value).padStart(2, "0");

/** `2026-10-24 10:44` in local time; an absent or broken time prints `—`. */
export function stamp(iso: string | undefined): string {
  if (iso === undefined) return "—";
  const date = new Date(iso);
  if (Number.isNaN(date.getTime())) return iso;
  return (
    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
    `${pad(date.getHours())}:${pad(date.getMinutes())}`
  );
}

/** `10:44` in local time. */
function clock(iso: string | undefined): string {
  if (iso === undefined) return "—";
  const date = new Date(iso);
  if (Number.isNaN(date.getTime())) return iso;
  return `${pad(date.getHours())}:${pad(date.getMinutes())}`;
}

/** `h3f2a1b8` for a stable message id; anything else is already short enough. */
export function shortHash(id: string): string {
  return /^h[0-9a-f]{12}$/.test(id) ? id.slice(0, 8) : id;
}

function oneLine(text: string): string {
  return text.replace(/\s+/g, " ").trim();
}

/** A branch summary with the message range it covers. */
export interface LogBranch {
  sessionId: string;
  title: string;
  asked: string;
  outcome: string;
  open: string;
  start: { id: string; label: string };
  end: { id: string; label: string };
  /** Messages in the branch, including the one that starts it. */
  count: number;
}

/** One message line in `log` (and the JSON shape). */
export interface LogMessage {
  id: string;
  label: string;
  at?: string;
  title: string;
  summary?: string;
  parent: string | null;
  /** The label of the parent when it lives in this session. */
  parentLabel?: string;
  links: string[];
  linkLabels: string[];
  /** Set on the message that starts a branch. */
  branch?: LineageNode["branch"];
  commits: string[];
}

export interface LogSession {
  sessionId: string;
  title: string;
  /** Who recorded the session (Story 9.3); absent on older records. */
  author?: string;
  startedAt: string;
  updatedAt: string;
  /** Newest first. */
  messages: LogMessage[];
  branches: LogBranch[];
}

export interface LogModel {
  sessions: LogSession[];
}

/**
 * The branch summaries of a session, in send order. A branch runs from the
 * message that carries it up to the message before the next branch starts (or
 * the end of the session), so the compressed view covers every message once a
 * summary exists.
 */
export function branchesOf(sessionId: string, messages: readonly ViewNode[]): LogBranch[] {
  const starts = messages.flatMap((message, index) =>
    message.branch === undefined ? [] : [{ index, branch: message.branch }],
  );
  return starts.map(({ index, branch }, position) => {
    const end = (starts[position + 1]?.index ?? messages.length) - 1;
    const first = messages[index] as ViewNode;
    const last = messages[end] as ViewNode;
    return {
      sessionId,
      title: branch.title,
      asked: branch.asked,
      outcome: branch.outcome,
      open: branch.open,
      start: { id: first.id, label: first.label ?? first.id },
      end: { id: last.id, label: last.label ?? last.id },
      count: end - index + 1,
    };
  });
}

function toLogSession(effective: EffectiveSession): LogSession {
  const { session, messages } = effective;
  const labels = new Map(messages.map((message) => [message.id, message.label ?? message.id]));
  const logMessages: LogMessage[] = [...messages].reverse().map((message) => {
    const parentLabel = typeof message.parent === "string" ? labels.get(message.parent) : undefined;
    return {
      id: message.id,
      label: message.label ?? message.id,
      ...(message.at === undefined ? {} : { at: message.at }),
      title: message.title,
      ...(message.summary === undefined ? {} : { summary: message.summary }),
      parent: message.parent ?? null,
      ...(parentLabel === undefined ? {} : { parentLabel }),
      links: message.links ?? [],
      linkLabels: (message.links ?? []).map((link) => labels.get(link) ?? link),
      ...(message.branch === undefined ? {} : { branch: message.branch }),
      commits: message.commits ?? [],
    };
  });
  return {
    sessionId: session.sessionId,
    title: session.title,
    ...(session.author === undefined ? {} : { author: session.author }),
    startedAt: session.startedAt,
    updatedAt: session.updatedAt,
    messages: logMessages,
    branches: branchesOf(session.sessionId, messages),
  };
}

export interface LogOptions {
  /** Only messages recorded here; a session id or any prefix of one. */
  session?: string | undefined;
  /** Maximum messages (or branches with `branchesOnly`). */
  limit?: number | undefined;
  /** Only the branch summaries: the compressed view. */
  branchesOnly?: boolean;
}

/**
 * The sessions a `--session` selector names: an exact id wins, otherwise an
 * unambiguous prefix. An unknown or ambiguous selector is a user error.
 */
export function selectSessions(
  sessions: readonly EffectiveSession[],
  prefix: string,
): EffectiveSession[] {
  const exact = sessions.filter((entry) => entry.session.sessionId === prefix);
  const matches =
    exact.length > 0
      ? exact
      : sessions.filter((entry) => entry.session.sessionId.startsWith(prefix));
  if (matches.length === 0) throw new CliError(`no session matches ${prefix}`);
  if (matches.length > 1) {
    const ids = matches.map((entry) => entry.session.sessionId).join(", ");
    throw new CliError(`"${prefix}" matches ${matches.length} sessions: ${ids}`);
  }
  return matches;
}

/**
 * The log model: sessions newest first, their messages newest first. `--session`
 * takes an exact id or an unambiguous prefix.
 */
export function buildLog(sessions: EffectiveSession[], opts: LogOptions = {}): LogModel {
  const selected = opts.session === undefined ? sessions : selectSessions(sessions, opts.session);

  const ordered = [...selected].sort(
    (a, b) =>
      b.session.startedAt.localeCompare(a.session.startedAt) ||
      a.session.sessionId.localeCompare(b.session.sessionId),
  );
  const model: LogModel = { sessions: ordered.map(toLogSession) };

  if (opts.limit !== undefined && opts.limit > 0) {
    let left = opts.limit;
    model.sessions = model.sessions.flatMap((session) => {
      if (left === 0) return [];
      if (opts.branchesOnly === true) {
        const branches = session.branches.slice(0, left);
        left -= branches.length;
        return branches.length === 0 ? [] : [{ ...session, messages: [], branches }];
      }
      const messages = session.messages.slice(0, left);
      left -= messages.length;
      return messages.length === 0 ? [] : [{ ...session, messages }];
    });
  }
  if (opts.branchesOnly === true) {
    model.sessions = model.sessions.map((session) => ({ ...session, messages: [] }));
  }
  return model;
}

function sessionHeading(session: LogSession): string {
  // An untitled session shows its id once, not as "id (id)".
  const title =
    session.title.trim() === ""
      ? session.sessionId
      : `${oneLine(session.title)} (${session.sessionId})`;
  const author = session.author === undefined ? "" : ` · by ${session.author}`;
  return `## ${title}${author} · ` + `${stamp(session.startedAt)} → ${stamp(session.updatedAt)}`;
}

function branchLines(branch: LogBranch): string[] {
  const count = `${branch.count} message${branch.count === 1 ? "" : "s"}`;
  return [
    `  ╭ ${branch.title}  ${branch.start.label}–${branch.end.label}, ${count}`,
    `    asked: ${branch.asked}`,
    `    outcome: ${branch.outcome}`,
    `    open: ${branch.open === "" ? "—" : branch.open}`,
  ];
}

function messageLine(message: LogMessage): string {
  const parts = [
    `  ${shortHash(message.id)}  ${message.label}  ${clock(message.at)}  ` +
      `${message.branch === undefined ? "" : `╭ ${message.branch.title} · `}${oneLine(message.title)}`,
  ];
  if (message.linkLabels.length > 0) parts.push(`  ↩ ${message.linkLabels.join(", ")}`);
  if (message.commits.length > 0)
    parts.push(`  [${message.commits.map((hash) => hash.slice(0, 7)).join(" ")}]`);
  return parts.join("");
}

/** The plain-text `log`, one line per array entry, newest first. */
export function formatLog(model: LogModel, branchesOnly = false): string[] {
  if (model.sessions.length === 0) return ["No recorded sessions yet."];
  const lines: string[] = [];
  for (const session of model.sessions) {
    lines.push(sessionHeading(session));
    if (branchesOnly) {
      if (session.branches.length === 0) lines.push("  (no branch summaries)");
      for (const branch of session.branches) lines.push(...branchLines(branch));
    } else if (session.messages.length === 0) {
      lines.push("  (no recorded messages)");
    } else {
      for (const message of session.messages) lines.push(messageLine(message));
    }
    lines.push("");
  }
  lines.pop();
  return lines;
}

/** A message reference as `show` prints and serializes it. */
export interface ShowRef {
  sessionId: string;
  id: string;
  label?: string;
  title?: string;
}

export interface RefHit {
  session: Session;
  messages: ViewNode[];
  message: ViewNode;
}

export type RefResult =
  | { kind: "ok"; hit: RefHit }
  | { kind: "ambiguous"; candidates: ShowRef[] }
  | { kind: "unknown"; reason: string }
  | { kind: "invalid"; reason: string };

const HASH_REF = /^h[0-9a-f]{6,12}$/;
const SESSION_LABEL_REF = /^([A-Za-z0-9][A-Za-z0-9_.-]{0,127}):m([1-9][0-9]*)$/;
/** A raw git commit hash: 7–40 lowercase hex, no `h` prefix (`h…` is a message). */
const COMMIT_REF = /^[0-9a-f]{7,40}$/;

/** A record may hold seven characters of a hash and git forty; either direction matches. */
function sameCommit(recorded: string, commit: string): boolean {
  return commit.startsWith(recorded) || recorded.startsWith(commit);
}

/**
 * Resolves a `<ref>` against every session. Errors stay data, so the command can
 * print the candidates before it exits non-zero.
 */
export function resolveRef(sessions: readonly EffectiveSession[], ref: string): RefResult {
  if (HASH_REF.test(ref)) {
    const hits = sessions.flatMap((entry) =>
      entry.messages
        .filter((message) => message.id.startsWith(ref))
        .map((message) => ({ entry, message })),
    );
    if (hits.length === 0) return { kind: "unknown", reason: `no recorded message matches ${ref}` };
    if (hits.length > 1) {
      return {
        kind: "ambiguous",
        candidates: hits.map(({ entry, message }) => ({
          sessionId: entry.session.sessionId,
          id: message.id,
          label: message.label ?? message.id,
          title: message.title,
        })),
      };
    }
    const hit = hits[0] as { entry: EffectiveSession; message: ViewNode };
    return {
      kind: "ok",
      hit: { session: hit.entry.session, messages: hit.entry.messages, message: hit.message },
    };
  }

  // A commit the `Thought:` trailer (Story 9.4) attached to a message opens that
  // message: `cogit show <commit-sha>` is the way from code back to the why.
  if (COMMIT_REF.test(ref)) {
    const hits = sessions.flatMap((entry) =>
      entry.messages
        .filter((message) => (message.commits ?? []).some((hash) => sameCommit(hash, ref)))
        .map((message) => ({ entry, message })),
    );
    if (hits.length === 0)
      return { kind: "unknown", reason: `no recorded thought for commit ${ref}` };
    if (hits.length > 1) {
      return {
        kind: "ambiguous",
        candidates: hits.map(({ entry, message }) => ({
          sessionId: entry.session.sessionId,
          id: message.id,
          label: message.label ?? message.id,
          title: message.title,
        })),
      };
    }
    const hit = hits[0] as { entry: EffectiveSession; message: ViewNode };
    return {
      kind: "ok",
      hit: { session: hit.entry.session, messages: hit.entry.messages, message: hit.message },
    };
  }

  const sessionLabel = SESSION_LABEL_REF.exec(ref);
  if (sessionLabel === null)
    return {
      kind: "invalid",
      reason:
        "use a message hash (h + 6..12 hex), <session-id-prefix>:mN, or a commit hash (7..40 hex)",
    };

  const prefix = sessionLabel[1] as string;
  const label = `m${sessionLabel[2] as string}`;
  const exact = sessions.filter((entry) => entry.session.sessionId === prefix);
  const matches =
    exact.length > 0
      ? exact
      : sessions.filter((entry) => entry.session.sessionId.startsWith(prefix));
  if (matches.length === 0) return { kind: "unknown", reason: `no session matches ${prefix}` };
  if (matches.length > 1) {
    return {
      kind: "ambiguous",
      candidates: matches.map((entry) => ({
        sessionId: entry.session.sessionId,
        id: entry.session.sessionId,
        label: entry.session.sessionId,
        title: entry.session.title,
      })),
    };
  }
  const entry = matches[0] as EffectiveSession;
  const message = entry.messages.find((candidate) => candidate.label === label);
  if (message === undefined)
    return {
      kind: "unknown",
      reason: `session ${entry.session.sessionId} has no recorded message ${label}`,
    };
  return { kind: "ok", hit: { session: entry.session, messages: entry.messages, message } };
}

/** One message with everything `show` prints, ready for text or JSON. */
export interface ShowModel {
  id: string;
  label: string;
  title: string;
  summary?: string;
  sessionId: string;
  sessionTitle: string;
  at?: string;
  parent: ShowRef | null;
  children: ShowRef[];
  links: ShowRef[];
  branch: LogBranch | null;
  decidedBy?: "user" | "agent" | "agreed";
  why?: string;
  alternatives?: LineageNode["alternatives"];
  agentDecisions?: LineageNode["agentDecisions"];
  work?: string[];
  commits: { hash: string; subject?: string }[];
  files?: string[];
  /** Null when the transcript is gone; absent when `--no-chat` skipped it. */
  chat?: {
    text: string;
    replies: string[];
    tools: { commands: number; files: string[]; other: number };
  } | null;
}

function refOf(sessions: readonly EffectiveSession[], ref: string, self: string): ShowRef {
  const colon = ref.indexOf(":");
  const sessionId = colon === -1 ? self : ref.slice(0, colon);
  const id = colon === -1 ? ref : ref.slice(colon + 1);
  const entry = sessions.find((candidate) => candidate.session.sessionId === sessionId);
  const message = entry?.messages.find((candidate) => candidate.id === id);
  return {
    sessionId,
    id,
    ...(message?.label === undefined ? {} : { label: message.label }),
    ...(message?.title === undefined ? {} : { title: message.title }),
  };
}

/** The branch a message sits in: the last branch that started at or before it. */
function branchAround(
  sessionId: string,
  messages: readonly ViewNode[],
  id: string,
): LogBranch | null {
  let start: ViewNode | null = null;
  for (const message of messages) {
    if (message.branch !== undefined) start = message;
    if (message.id === id) break;
  }
  if (start === null) return null;
  const branches = branchesOf(sessionId, messages);
  return branches.find((branch) => branch.start.id === start?.id) ?? null;
}

function conversationTurn(
  messages: SessionMessage[] | null,
  message: ViewNode,
): NonNullable<ShowModel["chat"]> | null {
  const turn = messages?.find(
    (candidate) => candidate.hash === message.id || candidate.label === message.label,
  );
  if (turn === undefined) return null;
  return { text: turn.text, replies: turn.replies, tools: turn.tools };
}

export interface ShowOptions {
  dir: string;
  ref: string;
  io: Io;
  /** False with `--no-chat`: skip the conversation section. */
  chat?: boolean;
}

/**
 * Reads one message: its place in the graph, its notes, its commits and the
 * conversation turn. An ambiguous or unknown ref prints what it can and throws,
 * so the CLI exits non-zero.
 */
export async function show(opts: ShowOptions): Promise<ShowModel> {
  const root = await openProject(opts.dir);
  const sessions = await loadEffectiveSessions(root, opts.io);
  const result = resolveRef(sessions, opts.ref);
  if (result.kind === "invalid") throw new CliError(`invalid ref "${opts.ref}": ${result.reason}`);
  if (result.kind === "unknown") {
    // The commit names a thought the record has not caught up with yet.
    const thought = COMMIT_REF.test(opts.ref)
      ? await readCommitThought(root, opts.ref, opts.io.env)
      : undefined;
    if (thought !== undefined) {
      const author = await readCommitAuthorEmail(root, opts.ref, opts.io.env);
      const me = await gitUserEmail(root, opts.io.env);
      const others =
        author !== undefined && me !== undefined && author.toLowerCase() !== me.toLowerCase();
      throw new CliError(
        others
          ? `commit ${opts.ref} comes from thought ${thought}, which is not in this clone's record: its author has not pushed it yet, or the commit came from a fork, whose record stays in the fork`
          : `commit ${opts.ref} comes from thought ${thought}, which is not recorded yet; it appears after the next record update`,
      );
    }
    throw new CliError(result.reason);
  }
  if (result.kind === "ambiguous") {
    for (const candidate of result.candidates) {
      opts.io.out(
        `  ${candidate.sessionId} · ${candidate.label}${candidate.id === candidate.label ? "" : ` (${candidate.id})`}  ${candidate.title}`,
      );
    }
    throw new CliError(
      COMMIT_REF.test(opts.ref)
        ? `commit ${opts.ref} comes from several thoughts; open one by its message hash`
        : `"${opts.ref}" is ambiguous; use a longer prefix`,
    );
  }

  const { session, messages, message } = result.hit;
  const sessionId = session.sessionId;

  const children: ShowRef[] = [];
  const seen = new Set<string>();
  for (const entry of sessions) {
    for (const candidate of entry.messages) {
      const parent = candidate.parent;
      const child =
        (entry.session.sessionId === sessionId && parent === message.id) ||
        parent === `${sessionId}:${message.id}`;
      if (!child) continue;
      const key = `${entry.session.sessionId}:${candidate.id}`;
      if (seen.has(key)) continue;
      seen.add(key);
      const ref = refOf(sessions, key, entry.session.sessionId);
      children.push(ref);
    }
  }

  const subjects =
    message.commits === undefined || message.commits.length === 0
      ? new Map<string, string>()
      : await readCommitSubjects(root, message.commits);

  const branch = branchAround(sessionId, messages, message.id);
  const turn = opts.chat === false ? null : await readSessionMessages(root, sessionId, opts.io.env);

  return {
    id: message.id,
    label: message.label ?? message.id,
    title: message.title,
    ...(message.summary === undefined ? {} : { summary: message.summary }),
    sessionId,
    sessionTitle: session.title,
    ...(message.at === undefined ? {} : { at: message.at }),
    parent:
      message.parent === null || message.parent === undefined
        ? null
        : refOf(sessions, message.parent, sessionId),
    children,
    links: (message.links ?? []).map((link) => refOf(sessions, link, sessionId)),
    branch: branch === null ? null : { ...branch, sessionId },
    ...(message.decidedBy === undefined ? {} : { decidedBy: message.decidedBy }),
    ...(message.why === undefined ? {} : { why: message.why }),
    ...(message.alternatives === undefined ? {} : { alternatives: message.alternatives }),
    ...(message.agentDecisions === undefined ? {} : { agentDecisions: message.agentDecisions }),
    ...(message.work === undefined ? {} : { work: message.work }),
    commits: (message.commits ?? []).map((hash) => {
      const subject = subjects.get(hash);
      return subject === undefined ? { hash } : { hash, subject };
    }),
    ...(message.files === undefined ? {} : { files: message.files }),
    ...(opts.chat === false ? {} : { chat: conversationTurn(turn, message) }),
  };
}

/** A ref as text: a bare label inside its own session, prefixed across sessions. */
function refText(ref: ShowRef, selfSessionId?: string): string {
  const label = ref.label === undefined ? ref.id : `${ref.label} ${shortHash(ref.id)}`;
  return selfSessionId !== undefined && ref.sessionId === selfSessionId
    ? label
    : `${ref.sessionId}:${label}`;
}

/** The plain-text `show`: the message, its graph neighbours, notes and turn. */
export function formatShow(model: ShowModel): string[] {
  const title = oneLine(model.sessionTitle) || model.sessionId;
  const lines: string[] = [
    `${model.id}  ${model.label}  ${model.title}`,
    `Session: ${title} (${model.sessionId}) · ${stamp(model.at)}`,
  ];
  if (model.parent !== null) lines.push(`Parent: ${refText(model.parent, model.sessionId)}`);
  if (model.children.length > 0)
    lines.push(
      `Children: ${model.children.map((ref) => refText(ref, model.sessionId)).join(", ")}`,
    );
  if (model.links.length > 0)
    lines.push(`Returns to: ${model.links.map((ref) => refText(ref, model.sessionId)).join(", ")}`);
  if (model.branch !== null) {
    const count = `${model.branch.count} message${model.branch.count === 1 ? "" : "s"}`;
    lines.push(
      `Branch: ${model.branch.title} (${model.branch.start.label}–${model.branch.end.label}, ${count})`,
    );
    lines.push(`  asked: ${model.branch.asked}`);
    lines.push(`  outcome: ${model.branch.outcome}`);
    lines.push(`  open: ${model.branch.open === "" ? "—" : model.branch.open}`);
  }
  if (model.decidedBy !== undefined) lines.push(`Decided by: ${model.decidedBy}`);
  if (model.why !== undefined) lines.push(`Why: ${model.why}`);
  if (model.alternatives !== undefined && model.alternatives.length > 0) {
    lines.push("Considered and rejected:");
    for (const alt of model.alternatives)
      lines.push(`  - ${alt.option}${alt.why === "" ? "" : ` — ${alt.why}`}`);
  }
  if (model.agentDecisions !== undefined && model.agentDecisions.length > 0) {
    lines.push("Agent decisions:");
    for (const decision of model.agentDecisions) {
      lines.push(`  - ${decision.title}${decision.why === "" ? "" : ` — ${decision.why}`}`);
      for (const alt of decision.alternatives ?? [])
        lines.push(`    not: ${alt.option}${alt.why === "" ? "" : ` — ${alt.why}`}`);
    }
  }
  if (model.work !== undefined && model.work.length > 0) {
    lines.push("What the agent did:");
    for (const item of model.work) lines.push(`  - ${item}`);
  }
  if (model.commits.length > 0) {
    lines.push("Commits:");
    for (const commit of model.commits)
      lines.push(
        `  ${commit.hash}${commit.subject === undefined ? " (not in this repository)" : ` ${commit.subject}`}`,
      );
  }
  if (model.files !== undefined && model.files.length > 0) {
    lines.push("Files:");
    for (const file of model.files) lines.push(`  ${file}`);
  }
  if (model.chat === null) {
    lines.push("Conversation: not available (the transcript is gone and nothing was stored)");
  } else if (model.chat !== undefined) {
    lines.push("Conversation:");
    lines.push(`  User: ${model.chat.text}`);
    for (const reply of model.chat.replies) lines.push(`  Agent: ${reply}`);
    const { commands, files, other } = model.chat.tools;
    const fileText =
      files.length === 0 ? "" : `, ${files.length} file${files.length === 1 ? "" : "s"}`;
    lines.push(
      `  Tools: ${commands} command${commands === 1 ? "" : "s"}${fileText}, ${other} other`,
    );
  }
  return lines;
}

export interface LogCommandOptions extends LogOptions {
  dir: string;
  io: Io;
  json?: boolean;
}

/** `cogit log [dir]`. */
export async function log(opts: LogCommandOptions): Promise<LogModel> {
  const root = await openProject(opts.dir);
  const sessions = await loadEffectiveSessions(root, opts.io);
  const model = buildLog(sessions, opts);
  if (opts.json === true) {
    opts.io.out(JSON.stringify(model, null, 2));
    return model;
  }
  for (const line of formatLog(model, opts.branchesOnly === true)) opts.io.out(line);
  return model;
}

/**
 * `./src\a.ts` and `src/a.ts` name the same file; the model stores forward-slash
 * paths without a leading `./` (Story 8.15).
 */
export function normalizeFilePath(file: string): string {
  return file
    .replace(/\\/g, "/")
    .replace(/^(\.\/)+/, "")
    .replace(/\/+$/, "");
}

/** The plain-text file history: one line per message, newest first. */
export function formatFileHistory(file: ViewFile): string[] {
  const count = `${file.count} message${file.count === 1 ? "" : "s"}`;
  const lines = [`${file.path}  ${count}  (newest first)`];
  for (const hit of file.hits) {
    const parts = [
      `  ${stamp(hit.at)}  ${shortHash(hit.messageId)}  ${hit.label}  ${oneLine(hit.title)}`,
    ];
    parts.push(`  · ${oneLine(hit.sessionTitle)}`);
    if (hit.branch !== undefined) parts.push(` ╭ ${oneLine(hit.branch)}`);
    if (hit.commits.length > 0)
      parts.push(`  [${hit.commits.map((hash) => hash.slice(0, 7)).join(" ")}]`);
    lines.push(parts.join(""));
  }
  return lines;
}

export interface FileLogOptions {
  dir: string;
  /** The file whose history to print, relative to the project. */
  file: string;
  io: Io;
  json?: boolean;
}

/**
 * `cogit log --file <path>`: the recorded messages that touched a file,
 * newest first — the CLI side of the map's files view (Story 8.15). Files come
 * from each message's own `files` plus the files of its commits read from git.
 */
export async function logFile(opts: FileLogOptions): Promise<ViewFile | null> {
  const root = await openProject(opts.dir);
  const sessions = await loadEffectiveSessions(root, opts.io);
  const hashes = new Set(
    sessions.flatMap((entry) => entry.messages.flatMap((message) => message.commits ?? [])),
  );
  let commitFiles: Map<string, string[]> = new Map();
  if (hashes.size > 0) {
    const gitRoot = await findGitRoot(root);
    if (gitRoot !== undefined)
      commitFiles = projectFiles(gitRoot, root, await readCommitFiles(gitRoot, hashes));
  }
  const sources: FileSourceSession[] = sessions.map(({ session, messages }) => ({
    sessionId: session.sessionId,
    title: session.title,
    messages,
  }));
  const wanted = normalizeFilePath(opts.file);
  const found = buildFileHistory(sources, commitFiles).find((file) => file.path === wanted);
  if (found === undefined) {
    opts.io.out(`No recorded message touched ${opts.file}.`);
    return null;
  }
  if (opts.json === true) {
    opts.io.out(JSON.stringify(found, null, 2));
    return found;
  }
  for (const line of formatFileHistory(found)) opts.io.out(line);
  return found;
}