Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
import { readdir, stat } from "node:fs/promises";
import { dirname, resolve } from "node:path";
import pkg from "../../package.json" with { type: "json" };
import { type ChatTurn, defaultAgent } from "../agents/index.js";
import { sessionIdentity } from "../author.js";
import {
type CommitChange,
findGitRoot,
projectFiles,
readCommitFiles,
readCommitSubjects,
refreshCogitGitignore,
} from "../git.js";
import { CliError, type Io } from "../io.js";
import {
hashTurns,
isRecorded,
type SessionMessage,
storedMessages,
upgradeSessionIds,
} from "../messages.js";
import { reconcileRecords, recordSyncStatus } from "../record-sync.js";
import { redactDeep } from "../redact.js";
import { Slug } from "../schema/common.js";
import { SESSION_SCHEMA, type Session } from "../schema/session.js";
import { readCaptures } from "../store/captures.js";
import { readProjectChanges } from "../store/changes.js";
import {
appendConversationHashes,
appendConversationTurns,
readConversationStore,
} from "../store/conversations.js";
import { applyEvents, readEvents } from "../store/events.js";
import { atomicWrite } from "../store/fs.js";
import { withLock } from "../store/lock.js";
import { readMapView } from "../store/map-view.js";
import { projectPaths } from "../store/paths.js";
import { resolveProjectRoot } from "../store/root.js";
import { loadAllSessions, loadConfig, loadProject } from "../store/stores.js";
import { attachThoughtTrailers, earliestSessionStart, readThoughtTrailers } from "../thought.js";
import { attachChanges } from "../view/change.js";
import { buildFileHistory, modelSessions } from "../view/files.js";
import { buildViewModel, embedViewModel, markBuiltBy } from "../view/lineage.js";
import type { LineageViewModel, ViewChatTurn, ViewPendingMessage } from "../view/model.js";
import {
buildPanel,
collectInboxForProject,
collectRegistryData,
type PanelData,
panelSettings,
} from "../view/panel.js";
import { switcherEntries } from "../view/switcher.js";
import { TEMPLATE_HTML } from "../view/template.js";
export interface BuildOptions {
dir: string;
io: Io;
/** Replaces the bundled template; tests inject a minimal page. */
templateHtml?: string;
/** `session write` rebuilds without printing a success line. */
quiet?: boolean;
}
/** How many characters of a not-yet-summarized message become its card title. */
export const PENDING_TITLE_LENGTH = 200;
export interface TranscriptViews {
/**
* The conversation of every session that shows messages, recorded or not. It
* goes into the page only, never into a session file.
*/
chats: Map<string, ViewChatTurn[]>;
/** User messages with no node yet, per session, titled for the map. */
pending: Map<string, ViewPendingMessage[]>;
/** The record as the map sees it: stable ids and the replayed structure. */
sessions: Session[];
/** User messages with no node yet, per session, counted from the transcripts. */
unrecorded: Map<string, number>;
}
/** Drops the fields only the drill-down needs (uuid, hints) and keeps the contract. */
function toViewTurn(turn: ChatTurn): ViewChatTurn {
return {
id: turn.hash ?? turn.id,
...(turn.label === undefined ? {} : { label: turn.label }),
at: turn.at,
text: turn.text,
replies: turn.replies,
tools: turn.tools,
};
}
/**
* Sessions the hooks have seen in this project that have no record yet: the
* first records come only after a few turns, and until then the map would not
* show the session at all. Each gets an empty record for this build only (never
* written), so its messages appear as unsummarized rows from the first one.
*/
async function unrecordedSessions(
root: string,
sessions: Session[],
transcripts: ReadonlyMap<string, string>,
): Promise<Session[]> {
const dir = dirname(projectPaths(root).state("x"));
let names: string[];
try {
names = await readdir(dir);
} catch {
return [];
}
const known = new Set(sessions.map((session) => session.sessionId));
const found: Session[] = [];
for (const name of names) {
if (!name.endsWith(".json")) continue;
const id = name.slice(0, -".json".length);
if (known.has(id) || !transcripts.has(id) || !Slug.safeParse(id).success) continue;
// Gone since the listing (the session just ended and was cleaned up): skip it.
const info = await stat(resolve(dir, name)).catch(() => undefined);
if (!info) continue;
const startedAt = (info.birthtimeMs > 0 ? info.birthtime : info.mtime).toISOString();
found.push({
schema: SESSION_SCHEMA,
sessionId: id,
agent: "claude-code",
title: "",
startedAt,
updatedAt: info.mtime.toISOString(),
status: { goal: "", done: [], pending: [], next: "" },
nodes: [],
});
}
return found;
}
/**
* Reads each session's conversation, preferring the project's own store and
* reading the transcript only for turns it does not hold yet. New turns are
* appended to the store, so the drill-down survives Claude Code deleting the
* transcript; a session whose transcript is gone (or unreadable) still shows what
* was stored. A transcript that cannot be read is a warning, never a lost map.
*/
async function readTranscriptViews(
sessions: Session[],
transcripts: ReadonlyMap<string, string>,
root: string,
io: Io,
): Promise<TranscriptViews> {
const agent = defaultAgent();
const chats = new Map<string, ViewChatTurn[]>();
const pending = new Map<string, ViewPendingMessage[]>();
const prepared: Session[] = [];
const unrecorded = new Map<string, number>();
for (const session of sessions) {
const file = transcripts.get(session.sessionId);
const recordsMessages = session.nodes.some((node) => node.kind === "message");
const roots = [session.worktree?.path, root].filter((r): r is string => Boolean(r));
let stored = await readConversationStore(root, session.sessionId);
let transcript: ChatTurn[] | null = null;
if (file) {
try {
transcript = await agent.readConversation(file);
} catch (err) {
if (recordsMessages)
io.warn(
`could not read the conversation of ${session.sessionId}: ${(err as Error).message}`,
);
}
}
const fromTranscript =
transcript && transcript.length > 0 ? hashTurns(session.sessionId, transcript) : null;
if (fromTranscript) {
const hashes = new Map(
fromTranscript.flatMap((turn) =>
turn.uuid === undefined ? [] : [[turn.uuid, turn.hash] as [string, string]],
),
);
try {
const appended = await appendConversationTurns(
root,
session.sessionId,
fromTranscript.map((turn) => agent.displayTurn(turn, roots)),
);
// The page reads these turns below, so it shows the answer this build just stored.
if (appended > 0) stored = await readConversationStore(root, session.sessionId);
// Turns stored before ids were stable get theirs now, before Claude Code
// deletes the transcript this hash comes from.
await appendConversationHashes(root, session.sessionId, hashes);
} catch (err) {
// Losing the transcript is a real risk, but a failed append must never
// fail the map: the page still shows this build's conversation.
io.warn(
`could not store the conversation of ${session.sessionId}: ${(err as Error).message}`,
);
}
}
const messages: SessionMessage[] | null = fromTranscript
? fromTranscript
: stored.length > 0
? storedMessages(session.sessionId, stored)
: transcript
? []
: null;
// Stable ids for old `m1` nodes, then the structure from the facts file.
const upgraded = messages ? upgradeSessionIds(session, messages) : session;
const events = await readEvents(root, session.sessionId);
const effective: Session = {
...upgraded,
nodes: applyEvents(upgraded.nodes, events),
};
prepared.push(effective);
const storedByUuid = new Map(stored.map((turn) => [turn.uuid, turn]));
let turns: ViewChatTurn[];
if (fromTranscript) {
turns = fromTranscript.map((turn) => {
const kept = turn.uuid === undefined ? undefined : storedByUuid.get(turn.uuid);
return kept
? toViewTurn({
...turn,
at: kept.at,
text: kept.text,
replies: kept.replies,
tools: kept.tools,
})
: toViewTurn(agent.displayTurn(turn, roots));
});
} else if (stored.length > 0) {
// No readable transcript: the store is all that is left. Its append-only
// order is the transcript order, so labels still line up.
turns = (messages ?? []).map((message) => toViewTurn(message));
} else {
turns = [];
}
const recorded = new Set(effective.nodes.map((node) => node.id));
const missing = (messages ?? []).filter((message) => !isRecorded(recorded, message));
if (missing.length > 0) {
pending.set(
session.sessionId,
missing.map((message) => ({
id: message.hash,
label: message.label,
at: message.at,
title: agent.excerpt(message.text, PENDING_TITLE_LENGTH) || "(blank message)",
})),
);
unrecorded.set(session.sessionId, missing.length);
}
if (recordsMessages || missing.length > 0) chats.set(session.sessionId, turns);
}
return { chats, pending, sessions: prepared, unrecorded };
}
interface CommitInfo {
/** Subject per recorded hash, for the tags and the drill-down (Story 8.8). */
subjects: Map<string, string>;
/** Project-relative files per recorded hash, for the file history (Story 8.15). */
files: Map<string, string[]>;
/** Numstat totals per recorded hash, for "how much code landed" (Story 10.3). */
changes: Map<string, CommitChange>;
}
/**
* Every commit hash the records list, with its subject and the files it changed
* read from git. A project outside git, or a commit git no longer knows, only
* means fewer tags and fewer files; the build never fails for it.
*/
async function commitInfo(root: string, sessions: Session[]): Promise<CommitInfo> {
const hashes = new Set<string>();
for (const session of sessions) {
for (const node of session.nodes) {
for (const hash of node.commits ?? []) hashes.add(hash);
}
}
if (hashes.size === 0) return { subjects: new Map(), files: new Map(), changes: new Map() };
const gitRoot = await findGitRoot(root);
if (gitRoot === undefined) return { subjects: new Map(), files: new Map(), changes: new Map() };
const [subjects, files, changes] = await Promise.all([
readCommitSubjects(gitRoot, hashes),
readCommitFiles(gitRoot, hashes),
readProjectChanges(root, hashes),
]);
return { subjects, files: projectFiles(gitRoot, root, files), changes };
}
/**
* Rebuilds `.cogit/map.html` from `project.json` and every session file,
* then refreshes the global panel. One unreadable session is a warning, never a
* failed build; an unwritable global directory only skips the panel.
*/
export async function buildProject(opts: BuildOptions): Promise<LineageViewModel> {
const { io } = opts;
const { root } = await resolveProjectRoot(opts.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);
for (const warning of project.warnings) io.warn(warning);
const paths = projectPaths(root);
const config = await loadConfig(io.env);
// Projects set up by an older version get the current rules on their next build,
// and every build keeps the refs and the files in step. An unwritable record or
// a failing git must never fail the map.
try {
await refreshCogitGitignore(root);
await reconcileRecords(root, io.env);
} catch (err) {
io.warn(`could not update the shared record: ${(err as Error).message}`);
}
// The map's switcher (8.12) and the panel read the same project list; collect
// it once. A broken registry is a warning: it must never fail the map.
const generatedAt = io.now();
let panelData: PanelData = { projects: [], inbox: [] };
try {
panelData = await collectRegistryData(io.env, generatedAt, io.warn, root);
} catch (err) {
io.warn(`could not read the project list: ${(err as Error).message}`);
}
const switcher = switcherEntries(panelData.projects, root);
// The Stop hook skips a turn while this lock is held, and a second build waits
// for the first instead of interleaving reads and writes of the same files.
const model = await withLock(
paths.lock("build"),
async () => {
const recorded = await loadAllSessions(root, io.warn);
const transcripts = await defaultAgent().collectTranscripts(io.env);
const sessions = [...recorded, ...(await unrecordedSessions(root, recorded, transcripts))];
const views = await readTranscriptViews(sessions, transcripts, root, io);
// The `Thought:` trailers git holds (Story 9.4) attach commits to the
// message they carry out, so the map, the file history and `blame` agree
// even when the agent's record did not list the hash.
const trailers = await readThoughtTrailers(root, {
env: io.env,
since: earliestSessionStart(views.sessions),
});
const withThoughts = attachThoughtTrailers(views.sessions, trailers);
const commits = await commitInfo(root, withThoughts);
// Story 10.3: each message carries the numstat totals of its linked
// commits. A project outside git simply has no numbers to show.
const withChanges = attachChanges(withThoughts, commits.changes);
const sync = await recordSyncStatus(root, io.env).catch(() => undefined);
const built = buildViewModel({
project: project.data,
sessions: withChanges,
path: root,
generatedAt,
transcripts: new Set(transcripts.keys()),
chats: views.chats,
pending: views.pending,
commitSubjects: commits.subjects,
commitFiles: commits.files,
// Over `file://` the settings modal shows these; a server page reads the
// live values instead, so a map built before a change still agrees.
settings: panelSettings(config),
viewer: await sessionIdentity(root, io.env),
// With the catch-up on, the hook records the tail at session end, so the
// count would only be a stale warning about work already scheduled.
unrecorded: config.sessionEndCatchUp ? undefined : views.unrecorded,
});
built.switcher = switcher;
if (sync?.downloadError !== undefined && !sync.downloaded) built.recordDownloadFailed = true;
const view = await readMapView(root);
built.rowWidths = view.rowWidths;
built.openSessions = view.open;
// Story 11.1: the map head carries this project's rows only. The panel
// already collected them from the registry; a project outside it (a
// broken registry, a hand-made directory) is read here instead.
const registered = panelData.projects.some(
(candidate) => resolve(candidate.path) === resolve(root),
);
built.inbox = registered
? panelData.inbox.filter((row) => resolve(row.projectPath) === resolve(root))
: await collectInboxForProject(
{ name: project.data.name, path: root },
views.sessions,
transcripts,
config,
generatedAt,
);
// The files view (8.15) unions each message's own files with the files of
// its commits, so a message the agent listed no paths for still lands.
built.files = buildFileHistory(modelSessions(built), commits.files);
// Story 15.1: the curated captured-work list, from the local store the
// distiller and the CLI write. A corrupt or missing file is an empty list.
built.captures = (await readCaptures(root, io.warn)).items;
// The skill already avoids secrets; this is the safety net before rendering.
const redacted = redactDeep(built);
if (redacted.count > 0)
io.warn(`redacted ${redacted.count} secret-looking value(s) in the map`);
const template = opts.templateHtml ?? TEMPLATE_HTML;
await atomicWrite(
paths.html,
markBuiltBy(embedViewModel(template, redacted.value), pkg.version),
);
if (!opts.quiet) io.out(`Wrote ${paths.html}`);
return redacted.value;
},
{ timeoutMs: 30_000 },
);
// The panel is derived state: a read-only home or a broken registry warning
// must never turn a successful map build into a failure.
try {
await buildPanel({
env: io.env,
io,
templateHtml: opts.templateHtml ?? TEMPLATE_HTML,
data: panelData,
});
} catch (err) {
io.warn(`could not build panel.html: ${(err as Error).message}`);
}
return model;
}