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 { execFile, spawn } from "node:child_process";
import { promisify } from "node:util";
import { cogitIgnored, findGitRoot, gitUserEmail, readCommitFiles } from "../git.js";
import { CliError, type Io } from "../io.js";
import { earliestSessionStart, readThoughtTrailers } from "../thought.js";
import type { ViewNode } from "../view/model.js";
import {
type EffectiveSession,
loadEffectiveSessions,
openProject,
shortHash,
stamp,
} from "./log.js";
const exec = promisify(execFile);
/**
* `cogit pr` (Story 10.1): a review-ready description of a branch, built from
* the thoughts the `Thought:` trailers point at. A reviewer sees the goal, the
* decisions and the rejected options instead of asking for them in comments.
* Only the record's own fields are read — never the conversation text or the
* user's raw prompt, because the PR may be public.
*/
/** GitHub's body limit is 65 536 characters; leave a little room. */
export const PR_CHAR_CAP = 60_000;
export interface PrBase {
/** The ref the user asked for, or `@{upstream}` / `main` / `master`. */
ref: string;
/** The full hash of the merge base `base..HEAD` starts from. */
commit: string;
}
/** One commit of the branch, with the record's thought and the files it changed. */
export interface PrCommit {
full: string;
short: string;
at: string;
subject: string;
/** The author's email, so a missing thought can be told apart: one's own, or someone else's. */
authorEmail?: string;
/** The messages the commit names; a squash can name several. */
thoughts?: string[];
/** Repository-relative paths; empty when git no longer has the commit. */
files: string[];
}
/** A commit no recorded thought explains. */
export interface PrUnlinkedCommit {
full: string;
short: string;
subject: string;
/** Set when the trailer names a thought the record does not hold yet. */
thought?: string;
/**
* True when someone else wrote the commit: their thought reaches this clone only
* once they push it, and never from a fork, whose record stays in the fork.
*/
others?: boolean;
}
export interface PrGoal {
text: string;
sessionId: string;
sessionTitle: string;
}
/** One session the branch's thoughts come from, with the label range it covers. */
export interface PrSessionLine {
sessionId: string;
shortId: string;
title: string;
startedAt: string;
updatedAt: string;
/** Message labels of the thoughts from this session in the branch. */
from: string;
to: string;
thoughtCount: number;
commitCount: number;
}
/** One thought with everything the description says about it. */
export interface PrThought {
id: string;
shortId: string;
label: string;
sessionId: string;
shortSessionId: string;
sessionTitle: string;
title: string;
summary?: string;
why?: string;
decidedBy?: "user" | "agent" | "agreed";
alternatives: { option: string; why: string }[];
agentDecisions: {
title: string;
why: string;
alternatives: { option: string; why: string }[];
}[];
commits: PrCommit[];
}
export interface PrModel {
base: PrBase;
head: string;
/** What the project does with its record: it travels, or it stays local. */
policy: "share" | "ignore";
goals: PrGoal[];
sessions: PrSessionLine[];
thoughts: PrThought[];
unlinked: PrUnlinkedCommit[];
}
/** `git log` for a branch, oldest first: `%H%x00%h%x00%cI%x00%ae%x00%s` per line. */
export function parsePrCommits(stdout: string): Omit<PrCommit, "files" | "thought">[] {
const out: Omit<PrCommit, "files" | "thought">[] = [];
for (const line of stdout.split("\n")) {
const [full, short, at, authorEmail, subject] = line.split("\0");
if (full === undefined || !/^[0-9a-f]{40}$/.test(full)) continue;
if (short === undefined || short === "") continue;
out.push({
full,
short,
at: at ?? "",
subject: subject ?? "",
...(authorEmail ? { authorEmail } : {}),
});
}
return out;
}
/** Git with `-C`, or undefined when the command fails (an unknown ref, no git). */
async function git(
root: string,
args: string[],
env: NodeJS.ProcessEnv,
): Promise<string | undefined> {
try {
const { stdout } = await exec("git", ["-C", root, ...args], { env });
return String(stdout).trim();
} catch {
return undefined;
}
}
/** The full hash a ref names, or undefined when it does not resolve. */
async function revParse(
root: string,
ref: string,
env: NodeJS.ProcessEnv,
): Promise<string | undefined> {
const out = await git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], env);
return out !== undefined && /^[0-9a-f]{40}$/.test(out) ? out : undefined;
}
/**
* The base of the review (Story 10.1): the upstream's merge base, else `main`,
* else `master`; an explicit base wins. A branch with none of these is a user
* error naming the command that fixes it.
*/
export async function resolvePrBase(
root: string,
requested: string | undefined,
env: NodeJS.ProcessEnv,
): Promise<PrBase> {
if (requested !== undefined) {
const commit = await revParse(root, requested, env);
if (commit === undefined) throw new CliError(`unknown base "${requested}"`);
return { ref: requested, commit };
}
const upstream = await revParse(root, "@{upstream}", env);
if (upstream !== undefined) {
const mergeBase = await git(root, ["merge-base", "HEAD", upstream], env);
if (mergeBase !== undefined && /^[0-9a-f]{40}$/.test(mergeBase))
return { ref: "@{upstream}", commit: mergeBase };
}
for (const branch of ["main", "master"]) {
const commit = await revParse(root, `refs/heads/${branch}`, env);
if (commit !== undefined) return { ref: branch, commit };
}
throw new CliError(
"cannot find a base: no upstream and neither main nor master; pass one, e.g. `cogit pr main`",
);
}
/** The commits of `base..HEAD`, oldest first — the order a reviewer reads them. */
async function readPrCommits(
root: string,
base: string,
head: string,
env: NodeJS.ProcessEnv,
): Promise<Omit<PrCommit, "files" | "thought">[]> {
const stdout = await git(
root,
["log", "--reverse", "--format=%H%x00%h%x00%cI%x00%ae%x00%s", `${base}..${head}`],
env,
);
return parsePrCommits(stdout ?? "");
}
function oneLine(text: string): string {
return text.replace(/\s+/g, " ").trim();
}
function titleOf(sessionId: string, title: string): string {
return title.trim() === "" ? sessionId : oneLine(title);
}
function labelIndex(label: string): number | undefined {
const match = /^m([1-9][0-9]*)$/.exec(label);
return match === null ? undefined : Number(match[1]);
}
export interface BuildPrInput {
base: PrBase;
head: string;
commits: readonly PrCommit[];
sessions: readonly EffectiveSession[];
policy: "share" | "ignore";
/** The local git user's email; a commit by anyone else is someone else's. */
userEmail?: string;
}
/**
* Groups the branch's commits by the thought their trailer names, in commit
* order (Story 10.1). A commit without a trailer, or whose thought the record
* does not hold yet, goes to `unlinked` with the trailer value for the reader.
*/
export function buildPrModel(input: BuildPrInput): PrModel {
const index = new Map<string, { entry: EffectiveSession; message: ViewNode }>();
for (const entry of input.sessions)
for (const message of entry.messages)
if (!index.has(message.id)) index.set(message.id, { entry, message });
const thoughts = new Map<string, PrThought>();
const unlinked: PrUnlinkedCommit[] = [];
const sessionOrder: string[] = [];
const entries = new Map<string, EffectiveSession>();
const labels = new Map<string, number[]>();
const thoughtCounts = new Map<string, number>();
const commitCounts = new Map<string, number>();
for (const commit of input.commits) {
const ids = commit.thoughts ?? [];
const known = ids.filter((id) => index.has(id));
if (known.length === 0) {
const named = ids[0];
const others =
commit.authorEmail !== undefined &&
input.userEmail !== undefined &&
commit.authorEmail.toLowerCase() !== input.userEmail.toLowerCase();
unlinked.push({
full: commit.full,
short: commit.short,
subject: commit.subject,
...(named === undefined ? {} : { thought: named }),
...(named !== undefined && others ? { others: true } : {}),
});
continue;
}
// A squash names several messages, but it is still one commit in each session.
const counted = new Set<string>();
for (const id of known) {
const hit = index.get(id) as { entry: EffectiveSession; message: ViewNode };
const { session } = hit.entry;
let thought = thoughts.get(id);
if (thought === undefined) {
const message = hit.message;
thought = {
id,
shortId: shortHash(id),
label: message.label ?? id,
sessionId: session.sessionId,
shortSessionId: session.sessionId.slice(0, 8),
sessionTitle: titleOf(session.sessionId, session.title),
title: message.title,
...(message.summary === undefined ? {} : { summary: message.summary }),
...(message.why === undefined ? {} : { why: message.why }),
...(message.decidedBy === undefined ? {} : { decidedBy: message.decidedBy }),
alternatives: message.alternatives ?? [],
agentDecisions: (message.agentDecisions ?? []).map((decision) => ({
title: decision.title,
why: decision.why,
alternatives: decision.alternatives ?? [],
})),
commits: [],
};
thoughts.set(id, thought);
if (!entries.has(session.sessionId)) {
sessionOrder.push(session.sessionId);
entries.set(session.sessionId, hit.entry);
labels.set(session.sessionId, []);
thoughtCounts.set(session.sessionId, 0);
commitCounts.set(session.sessionId, 0);
}
thoughtCounts.set(session.sessionId, (thoughtCounts.get(session.sessionId) ?? 0) + 1);
}
thought.commits.push(commit);
labels.get(session.sessionId)?.push(labelIndex(thought.label) ?? 0);
if (!counted.has(session.sessionId)) {
counted.add(session.sessionId);
commitCounts.set(session.sessionId, (commitCounts.get(session.sessionId) ?? 0) + 1);
}
}
}
const goals: PrGoal[] = [];
const seenGoals = new Set<string>();
const sessions: PrSessionLine[] = [];
for (const sessionId of sessionOrder) {
const entry = entries.get(sessionId);
if (entry === undefined) continue;
const session = entry.session;
const title = titleOf(sessionId, session.title);
const goal = oneLine(session.status.goal);
if (goal !== "" && !seenGoals.has(goal)) {
seenGoals.add(goal);
goals.push({ text: goal, sessionId, sessionTitle: title });
}
const numbers = labels.get(sessionId) ?? [];
sessions.push({
sessionId,
shortId: sessionId.slice(0, 8),
title,
startedAt: session.startedAt,
updatedAt: session.updatedAt,
from: numbers.length === 0 ? "—" : `m${Math.min(...numbers)}`,
to: numbers.length === 0 ? "—" : `m${Math.max(...numbers)}`,
thoughtCount: thoughtCounts.get(sessionId) ?? 0,
commitCount: commitCounts.get(sessionId) ?? 0,
});
}
return {
base: input.base,
head: input.head,
policy: input.policy,
goals,
sessions,
thoughts: [...thoughts.values()],
unlinked,
};
}
export interface PrFormatOptions {
includeFiles: boolean;
includeSummaries: boolean;
/** What the size cap dropped, said at the end of the description. */
dropped?: ("files" | "summaries")[];
}
function alternativeLine(alt: { option: string; why: string }, indent = ""): string {
const why = alt.why.trim() === "" ? "" : ` — ${oneLine(alt.why)}`;
return `${indent}- considered and rejected: ${oneLine(alt.option)}${why}`;
}
function decisionLines(thought: PrThought): string[] {
const lines: string[] = [];
if (thought.why !== undefined && thought.why.trim() !== "")
lines.push(`- Why: ${oneLine(thought.why)}`);
if (thought.decidedBy !== undefined) lines.push(`- Decided by: ${thought.decidedBy}`);
for (const alt of thought.alternatives) lines.push(alternativeLine(alt));
for (const decision of thought.agentDecisions) {
const why = decision.why.trim() === "" ? "" : ` — ${oneLine(decision.why)}`;
lines.push(`- agent decision: ${oneLine(decision.title)}${why}`);
for (const alt of decision.alternatives) lines.push(alternativeLine(alt, " "));
}
return lines;
}
/** The Markdown body of the PR, in the order Story 10.1 fixes. */
export function formatPr(model: PrModel, opts: PrFormatOptions): string {
const lines: string[] = ["## Goal"];
if (model.goals.length === 0) {
lines.push("_No session goal was recorded._");
} else {
for (const goal of model.goals)
lines.push(`- ${oneLine(goal.text)} — ${goal.sessionTitle} (${goal.sessionId.slice(0, 8)})`);
}
lines.push("", "## Sessions");
if (model.sessions.length === 0) {
lines.push("_No recorded session is behind these commits._");
} else {
lines.push("Open a whole session with `cogit log --session <id>` or the map.");
for (const session of model.sessions) {
const range = session.from === session.to ? session.from : `${session.from}–${session.to}`;
lines.push(
`- ${session.title} (${session.shortId}) · ${range} · ` +
`${stamp(session.startedAt)} → ${stamp(session.updatedAt)}`,
);
}
}
lines.push("", "## Thoughts");
if (model.thoughts.length === 0) {
lines.push("_No recorded thought is behind these commits._");
} else {
for (const thought of model.thoughts) {
lines.push(
"",
`### \`${thought.shortId}\` ${thought.shortSessionId}:${thought.label} — ` +
`${oneLine(thought.title)}`,
);
if (opts.includeSummaries && thought.summary !== undefined && thought.summary.trim() !== "")
lines.push("", oneLine(thought.summary));
const decisions = decisionLines(thought);
if (decisions.length > 0) lines.push("", ...decisions);
lines.push("", "Commits:");
for (const commit of thought.commits) {
lines.push(`- \`${commit.short}\` ${oneLine(commit.subject)}`);
if (opts.includeFiles) for (const file of commit.files) lines.push(` - \`${file}\``);
}
}
}
lines.push("", "## Commits without a recorded thought");
if (model.unlinked.length === 0) {
lines.push("_None: every commit carries a recorded thought._");
} else {
for (const commit of model.unlinked) {
const thought =
commit.thought === undefined
? ""
: commit.others === true
? ` — thought \`${commit.thought}\` is not in this clone's record: its author has ` +
"not pushed it yet, or it came from a fork, whose record stays in the fork"
: ` — thought \`${commit.thought}\` not recorded yet`;
lines.push(`- \`${commit.short}\` ${oneLine(commit.subject)}${thought}`);
}
}
lines.push("", "## Dig deeper");
lines.push(
"- `cogit show <message-hash>` opens a thought: its decisions, the options it rejected, " +
"and the conversation turn for whoever has it locally.",
"- `cogit show <sha>` opens the thought behind a commit.",
model.policy === "ignore"
? "- This project keeps its record out of git, so these hashes resolve only on the " +
"author's machine; ask the author to run `cogit show`."
: "- This project shares its record, so a reviewer with cogit in their clone gets the " +
"same `cogit show` output once the author has pushed.",
);
const dropped = opts.dropped ?? [];
if (dropped.length > 0) {
const names = dropped.map((item) => (item === "files" ? "file lists" : "summaries"));
const text = names.length === 1 ? names[0] : `${names[0]} and ${names[1]}`;
lines.push("", `_Left out to stay under the size cap: ${text}._`);
}
return lines.join("\n");
}
export interface PrRendered {
text: string;
dropped: ("files" | "summaries")[];
truncated: boolean;
}
/**
* Fits the description under the cap by dropping the file lists first, then the
* summaries (Story 10.1), and says what was left out. A description still over
* the cap after both is cut, so GitHub never refuses the body.
*/
export function renderPr(model: PrModel, cap = PR_CHAR_CAP): PrRendered {
const levels: {
includeFiles: boolean;
includeSummaries: boolean;
dropped: ("files" | "summaries")[];
}[] = [
{ includeFiles: true, includeSummaries: true, dropped: [] },
{ includeFiles: false, includeSummaries: true, dropped: ["files"] },
{ includeFiles: false, includeSummaries: false, dropped: ["files", "summaries"] },
];
for (const level of levels) {
const text = formatPr(model, level);
if (text.length <= cap) return { text, dropped: level.dropped, truncated: false };
}
const full = formatPr(model, levels[2] as (typeof levels)[number]);
const note =
"\n\n_Truncated to fit the size cap; file lists and summaries were left out. " +
"Open a thought with `cogit show` for the rest._";
if (note.length >= cap)
return { text: note.slice(0, cap), dropped: ["files", "summaries"], truncated: true };
return {
text: full.slice(0, cap - note.length) + note,
dropped: ["files", "summaries"],
truncated: true,
};
}
const CLIPBOARD_TOOLS: [string, string[]][] = [
["wl-copy", []],
["xclip", ["-selection", "clipboard"]],
["pbcopy", []],
["clip", []],
];
/** Pipes text into a process, resolving false when it is missing or fails. */
function pipe(
command: string,
args: string[],
text: string,
env: NodeJS.ProcessEnv,
): Promise<boolean> {
return new Promise((resolve) => {
let settled = false;
const done = (ok: boolean): void => {
if (settled) return;
settled = true;
resolve(ok);
};
const child = spawn(command, args, { env, stdio: ["pipe", "ignore", "ignore"] });
child.on("error", () => done(false));
child.on("close", (code) => done(code === 0));
child.stdin.on("error", () => done(false));
child.stdin.end(text);
});
}
/** Copies with the first clipboard tool that exists; false when there is none. */
export async function copyToClipboard(
text: string,
env: NodeJS.ProcessEnv = process.env,
): Promise<boolean> {
for (const [command, args] of CLIPBOARD_TOOLS) {
if (await pipe(command, args, text, env)) return true;
}
return false;
}
export interface PrOptions {
dir: string;
/** Base ref; default: the upstream's merge base, else main, else master. */
base?: string | undefined;
io: Io;
json?: boolean;
copy?: boolean;
/** Size cap for tests; defaults to `PR_CHAR_CAP`. */
cap?: number;
}
/** `cogit pr [base]`: reads the record and the branch, prints the description. */
export async function pr(opts: PrOptions): Promise<PrModel> {
const root = await openProject(opts.dir);
const gitRoot = await findGitRoot(root);
if (gitRoot === undefined) throw new CliError("not in a git repository");
const env = opts.io.env;
const head = await revParse(gitRoot, "HEAD", env);
if (head === undefined) throw new CliError("HEAD has no commits yet");
const base = await resolvePrBase(gitRoot, opts.base, env);
const commits = await readPrCommits(gitRoot, base.commit, head, env);
const sessions = await loadEffectiveSessions(root, opts.io);
const userEmail = await gitUserEmail(gitRoot, env);
const trailers =
commits.length === 0
? new Map<string, string[]>()
: await readThoughtTrailers(gitRoot, {
env,
since: earliestSessionStart(sessions.map((entry) => entry.session)),
});
const files =
commits.length === 0
? new Map<string, string[]>()
: await readCommitFiles(
gitRoot,
commits.map((commit) => commit.full),
);
const model = buildPrModel({
base,
head,
policy: (await cogitIgnored(root)) ? "ignore" : "share",
...(userEmail === undefined ? {} : { userEmail }),
sessions,
commits: commits.map((commit) => {
const thoughts = trailers.get(commit.full);
return {
...commit,
files: files.get(commit.full) ?? [],
...(thoughts === undefined ? {} : { thoughts }),
};
}),
});
const rendered = renderPr(model, opts.cap ?? PR_CHAR_CAP);
if (opts.copy === true && !(await copyToClipboard(rendered.text, env))) {
opts.io.warn(
"could not copy: no clipboard tool found (wl-copy, xclip, pbcopy or clip); the Markdown is on stdout",
);
}
if (opts.json === true) {
opts.io.out(
JSON.stringify(
{
...model,
rendered: { dropped: rendered.dropped, truncated: rendered.truncated },
},
null,
2,
),
);
return model;
}
for (const line of rendered.text.split("\n")) opts.io.out(line);
return model;
}