cueloop 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/open-target.ts

@@ -0,0 +1,128 @@
+/**
+ * Primitive-first review-open resolution: turn a primitive (plan/diff/review) plus an
+ * optional id-or-title selector into a single session to open, or a clear
+ * miss. Pure over a session list so it unit-tests without a daemon or a TUI -
+ * main.ts fetches the sessions and prints the miss messages.
+ *
+ * Rules, in order:
+ *   - no selector opens the latest pending session in scope (most recent
+ *     createdAt, verdict still open) - the `--latest` default;
+ *   - a selector that exactly equals a session id opens that session, pending
+ *     or resolved;
+ *   - otherwise the selector matches session titles, case-insensitive: an
+ *     exact title wins, else a unique substring match wins, else the substring
+ *     candidates are reported as ambiguous.
+ * Every lookup is scoped by the caller's `match` predicate, so a primitive only
+ * ever resolves to its own artifact kind.
+ */
+
+import type { Thread } from "@cueloop/schema";
+
+/**
+ * The primitive scopes, kept disjoint on purpose so a single session never resolves
+ * under two primitives. A PR review is a diff artifact that carries a `pr`
+ * reference (openReview maps a top-level `pr` into `meta.pr`), so the plain
+ * diff scope must exclude those - otherwise `cueloop diff` and `cueloop
+ * review` would both open the same pending PR review.
+ */
+export function isPlanReview(session: Thread): boolean {
+  return session.artifact.type === "plan";
+}
+export function isReplyReview(session: Thread): boolean {
+  return session.artifact.type === "reply";
+}
+export function isPrototypeReview(session: Thread): boolean {
+  return session.artifact.type === "prototype";
+}
+export function isDiffReview(session: Thread): boolean {
+  return session.artifact.type === "diff" && session.artifact.meta.pr === undefined;
+}
+export function isPrReview(session: Thread): boolean {
+  return session.artifact.type === "diff" && session.artifact.meta.pr !== undefined;
+}
+
+/** Session ids are minted with this prefix; the id-vs-title split lives here. */
+export function isSessionId(value: string): boolean {
+  return value.startsWith("ses_");
+}
+
+export interface OpenTargetQuery {
+  /** Only sessions this predicate accepts are eligible - the primitive's artifact scope. */
+  match: (session: Thread) => boolean;
+  /** Positional id-or-title selector; absent means "latest pending". */
+  selector?: string;
+}
+
+export type OpenTarget =
+  | { kind: "session"; sessionId: string }
+  | { kind: "no-pending" }
+  | { kind: "no-match"; selector: string }
+  | { kind: "ambiguous"; selector: string; titles: string[] };
+
+/** Most-recent-first, so the head of a sorted list is always the latest. */
+function newestFirst(left: Thread, right: Thread): number {
+  return right.createdAt.localeCompare(left.createdAt);
+}
+
+export function resolveOpenTarget(sessions: Thread[], query: OpenTargetQuery): OpenTarget {
+  const scoped = sessions.filter(query.match);
+
+  if (query.selector === undefined) {
+    const latestPending = scoped
+      .filter((candidate) => candidate.status === "pending")
+      .sort(newestFirst)[0];
+
+    return latestPending
+      ? { kind: "session", sessionId: latestPending.id }
+      : { kind: "no-pending" };
+  }
+
+  const selector = query.selector;
+  const byId = scoped.find((candidate) => candidate.id === selector);
+
+  if (byId) return { kind: "session", sessionId: byId.id };
+
+  const loweredSelector = selector.toLowerCase();
+  const titled = scoped.filter((candidate) => (candidate.artifact.meta.title ?? "").length > 0);
+
+  const exactTitle = titled
+    .filter((candidate) => candidate.artifact.meta.title!.toLowerCase() === loweredSelector)
+    .sort(newestFirst)[0];
+
+  if (exactTitle) return { kind: "session", sessionId: exactTitle.id };
+
+  const substringMatches = titled
+    .filter((candidate) => candidate.artifact.meta.title!.toLowerCase().includes(loweredSelector))
+    .sort(newestFirst);
+
+  if (substringMatches.length === 1) return { kind: "session", sessionId: substringMatches[0]!.id };
+  if (substringMatches.length === 0) return { kind: "no-match", selector };
+
+  return {
+    kind: "ambiguous",
+    selector,
+    titles: substringMatches.map((candidate) => candidate.artifact.meta.title!),
+  };
+}
+
+/**
+ * The reviewer-facing line for a miss, in the "working tree is clean - nothing
+ * to review" tone. `label` is the human word for the primitive's scope ("plan",
+ * "diff", "PR"). The "session" outcome has no message - the caller opens it.
+ */
+export function openTargetMessage(
+  label: string,
+  target: Exclude<OpenTarget, { kind: "session" }>,
+): string {
+  switch (target.kind) {
+    case "no-pending":
+      return `no pending ${label} review - nothing to open`;
+    case "no-match":
+      return `no ${label} review matches "${target.selector}" - nothing to open`;
+    case "ambiguous":
+      return [
+        `"${target.selector}" matches several ${label} reviews - name one:`,
+        ...target.titles.map((title) => `  - ${title}`),
+      ].join("\n");
+  }
+}

package/src/pr.ts

@@ -1,12 +1,12 @@
 /**
- * PR review entry (#18): `cueloop review <pr>` fetches the PR diff through the
+ * PR review entry: `cueloop review <pr>` fetches the PR diff through the
  * user's `gh` CLI (auth fully delegated), opens a diff session, and posts the
  * verdict back to the PR as a real review when the session resolves.
  * `cueloop review-post <session-id> <pr>` is the non-interactive post-back
  * half for agents and scripts.
  */
 
-import type { ReviewSession, VerdictKind } from "@cueloop/schema";
+import type { Thread, VerdictKind } from "@cueloop/schema";
 import { DaemonClient } from "@cueloop/daemon/client";
 import { openReview } from "@cueloop/daemon/review";
 import { parseArgs } from "./args";
@@ -29,6 +29,7 @@ async function gh(args: string[]): Promise<GhResult> {
     new Response(proc.stderr).text(),
     proc.exited,
   ]);
+
   return { code, stdout, stderr };
 }
 
@@ -42,20 +43,27 @@ const VERDICT_FLAG: Record<VerdictKind, string> = {
 export async function reviewCommand(argv: string[]): Promise<number> {
   const { positional, flags } = parseArgs(argv);
   const pr = positional[0];
+
   if (!pr) {
     console.error("usage: cueloop review <pr> [--no-tui]");
+
     return 2;
   }
   const diff = await gh(["pr", "diff", pr]);
+
   if (diff.code !== 0) {
     console.error(diff.stderr.trim() || `gh pr diff ${pr} failed (exit ${diff.code})`);
+
     return 1;
   }
   if (!diff.stdout.trim()) {
     console.error(`PR ${pr} has an empty diff - nothing to review`);
+
     return 1;
   }
   const client = await DaemonClient.connect({ autostart: true });
+  // A PR diff is a partial patch with no full file contents, so no `files` here;
+  // hunk curation stays disabled for PR reviews (see diff-hunk-curate.ts).
   const review = await openReview(client, {
     type: "diff",
     content: diff.stdout,
@@ -63,21 +71,27 @@ export async function reviewCommand(argv: string[]): Promise<number> {
     pr,
   });
   const session = review.session;
+
   client.close();
 
   if (flags["no-tui"]) {
     console.log(JSON.stringify(session, null, 2));
+
     return 0;
   }
 
   const { runClient } = await import("@cueloop/client");
+
   await runClient({ sessionId: session.id });
 
   const after = await getSession(session.id);
+
   if (after.status !== "resolved" || !after.verdict) {
     console.log(`session ${session.id} is unresolved - nothing was posted to PR ${pr}`);
+
     return 0;
   }
+
   return postVerdict(after, pr);
 }
 
@@ -85,20 +99,26 @@ export async function reviewPostCommand(argv: string[]): Promise<number> {
   const { positional } = parseArgs(argv);
   const sessionId = positional[0];
   const pr = positional[1];
+
   if (!sessionId || !pr) {
     console.error("usage: cueloop review-post <session-id> <pr>");
+
     return 2;
   }
   const session = await getSession(sessionId);
+
   if (session.status !== "resolved" || !session.verdict) {
     console.error(`session ${sessionId} is unresolved - nothing was posted to PR ${pr}`);
+
     return 1;
   }
+
   return postVerdict(session, pr);
 }
 
-async function getSession(id: string): Promise<ReviewSession> {
+async function getSession(id: string): Promise<Thread> {
   const client = await DaemonClient.connect({ autostart: true });
+
   try {
     return await client.sessionGet(id);
   } finally {
@@ -107,13 +127,23 @@ async function getSession(id: string): Promise<ReviewSession> {
 }
 
 /** Post the resolved session's verdict to the PR: feedback.md is the review body. */
-async function postVerdict(session: ReviewSession, pr: string): Promise<number> {
+async function postVerdict(session: Thread, pr: string): Promise<number> {
   const verdict = session.verdict!;
-  const result = await gh(["pr", "review", pr, VERDICT_FLAG[verdict.kind], "--body", verdict.feedback]);
+  const result = await gh([
+    "pr",
+    "review",
+    pr,
+    VERDICT_FLAG[verdict.kind],
+    "--body",
+    verdict.feedback,
+  ]);
+
   if (result.code !== 0) {
     console.error(result.stderr.trim() || `gh pr review ${pr} failed (exit ${result.code})`);
+
     return 1;
   }
   console.log(`posted ${verdict.kind} review to PR ${pr} (session ${session.id})`);
+
   return 0;
 }

package/src/refine-command.test.ts

@@ -0,0 +1,158 @@
+/** refine builds a corpus report from stored sessions and skips sessions it has already analyzed on a later run. */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Annotation, Thread, Verdict, VerdictKind } from "@cueloop/schema";
+import { ThreadStore } from "@cueloop/daemon/store";
+import { reportsDir } from "@cueloop/daemon/paths";
+import { buildRefineReport, refineCommand } from "./refine-command";
+
+function tempHome(): string {
+  return mkdtempSync(join(tmpdir(), "cueloop-refine-home-"));
+}
+
+function annotation(quote: string, body: string): Annotation {
+  return {
+    id: `a_${quote}`,
+    kind: "comment",
+    anchor: { quote, prefix: "", suffix: "" },
+    body,
+    createdAt: "2026-08-20T10:00:00Z",
+  };
+}
+
+function verdict(kind: VerdictKind): Verdict {
+  return { kind, summary: "", feedback: "", resolvedAt: "2026-08-20T11:00:00Z" };
+}
+
+function session(
+  id: string,
+  overrides: Partial<Thread> & { type?: Thread["artifact"]["type"] } = {},
+): Thread {
+  const { type, ...rest } = overrides;
+
+  return {
+    schemaVersion: "1",
+    id,
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: type ?? "plan", content: "", meta: {} },
+    revisions: [],
+    annotations: [],
+    verdict: null,
+    status: "pending",
+    createdAt: "2026-08-20T10:00:00Z",
+    ...rest,
+  };
+}
+
+describe("buildRefineReport", () => {
+  test("reports the analyzed and total counts, distributions, and annotations", () => {
+    // Arrange
+    const analyzed = [
+      session("ses_a", { verdict: verdict("approve"), status: "resolved" }),
+      session("ses_b", {
+        type: "diff",
+        verdict: verdict("request_changes"),
+        status: "resolved",
+        annotations: [annotation("skip tests", "please add a regression test")],
+      }),
+    ];
+
+    // Act
+    const markdown = buildRefineReport(analyzed, 3, "2026-08-26T00:00:00.000Z");
+
+    // Assert
+    expect(markdown).toContain("2 sessions analyzed (3 total).");
+    expect(markdown).toContain("- plan: 1");
+    expect(markdown).toContain("- diff: 1");
+    expect(markdown).toContain("- approve: 1");
+    expect(markdown).toContain("- request changes: 1");
+    expect(markdown).toContain("skip tests");
+    expect(markdown).toContain("please add a regression test");
+  });
+
+  test("notes when there are no reviewer annotations", () => {
+    // Act
+    const markdown = buildRefineReport([], 0, "2026-08-26T00:00:00.000Z");
+
+    // Assert
+    expect(markdown).toContain("0 sessions analyzed (0 total).");
+    expect(markdown).toContain("No reviewer annotations in the analyzed sessions.");
+  });
+});
+
+describe("refineCommand", () => {
+  test("writes a report, skips signal-free sessions, and consumes only resolved sessions", async () => {
+    // Arrange
+    const home = tempHome();
+    const store = new ThreadStore(home);
+
+    store.upsert(session("ses_a", { verdict: verdict("approve"), status: "resolved" }));
+    store.upsert(
+      session("ses_b", {
+        verdict: verdict("request_changes"),
+        status: "resolved",
+        annotations: [annotation("wrong file", "this belongs in store.ts")],
+      }),
+    );
+    store.upsert(
+      session("ses_pending", { annotations: [annotation("open point", "still deciding")] }),
+    );
+    store.upsert(session("ses_empty"));
+    const reportPath = join(reportsDir(home), "report.md");
+
+    // Act
+    const firstCode = await refineCommand(["--home", home]);
+
+    // Assert
+    expect(firstCode).toBe(0);
+    expect(readFileSync(reportPath, "utf8")).toContain("3 sessions analyzed (4 total).");
+
+    // Act
+    await refineCommand(["--home", home]);
+
+    // Assert
+    expect(readFileSync(reportPath, "utf8")).toContain("1 sessions analyzed (4 total).");
+  });
+
+  test("re-analyzes a resolved session that is reopened and resolved again with new feedback", async () => {
+    // Arrange
+    const home = tempHome();
+    const store = new ThreadStore(home);
+
+    store.upsert(
+      session("ses_x", {
+        verdict: verdict("approve"),
+        status: "resolved",
+        annotations: [annotation("first", "one")],
+      }),
+    );
+    const reportPath = join(reportsDir(home), "report.md");
+
+    // Act
+    await refineCommand(["--home", home]);
+
+    // Assert
+    expect(readFileSync(reportPath, "utf8")).toContain("1 sessions analyzed (1 total).");
+
+    // Arrange
+    store.upsert(
+      session("ses_x", {
+        verdict: { ...verdict("request_changes"), resolvedAt: "2026-08-21T09:00:00Z" },
+        status: "resolved",
+        annotations: [annotation("first", "one"), annotation("second", "two")],
+      }),
+    );
+
+    // Act
+    await refineCommand(["--home", home]);
+
+    // Assert
+    const secondReport = readFileSync(reportPath, "utf8");
+
+    expect(secondReport).toContain("1 sessions analyzed (1 total).");
+    expect(secondReport).toContain("two");
+  });
+});

package/src/refine-command.ts

@@ -0,0 +1,262 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cueloopHome, reportsDir } from "@cueloop/daemon/paths";
+import { ThreadStore } from "@cueloop/daemon/store";
+import {
+  LATEST_REPORT_FILENAME,
+  parseRefineState,
+  pruneExpiredReports,
+  resolveCleanupPeriodDays,
+  timestampedReportFilename,
+} from "@cueloop/daemon/retention";
+import { isAgentNote, type Annotation, type Thread } from "@cueloop/schema";
+import { parseArgs, stringFlag } from "./args";
+
+const DEFAULT_SESSION_LIMIT = 200;
+const QUOTE_LIMIT = 60;
+const BODY_LIMIT = 100;
+
+interface AnnotatedEntry {
+  annotation: Annotation;
+  session: Thread;
+}
+
+export async function refineCommand(argv: string[]): Promise<number> {
+  const { flags } = parseArgs(argv);
+  const home = stringFlag(flags, "home") ?? cueloopHome();
+  const limit = parseLimit(stringFlag(flags, "limit"));
+  const nowMs = Date.now();
+
+  const store = new ThreadStore(home);
+
+  store.recover();
+  const all = store.list();
+
+  const analyzedState = readState(home);
+  const fresh = all.filter(
+    (session) => analyzedState.get(session.id) !== analysisFingerprint(session),
+  );
+  const analyzed = fresh.filter(hasReviewSignal).slice(0, limit);
+
+  const markdown = buildRefineReport(analyzed, all.length, new Date(nowMs).toISOString());
+
+  const directory = reportsDir(home);
+
+  mkdirSync(directory, { recursive: true });
+  pruneExpiredReports(directory, resolveCleanupPeriodDays(), nowMs);
+  const latestPath = join(directory, LATEST_REPORT_FILENAME);
+  const timestampedPath = join(directory, timestampedReportFilename(nowMs));
+
+  writeFileSync(latestPath, markdown);
+  writeFileSync(timestampedPath, markdown);
+
+  for (const session of analyzed) {
+    if (session.status === "resolved") analyzedState.set(session.id, analysisFingerprint(session));
+  }
+  writeState(home, analyzedState);
+
+  console.log(
+    JSON.stringify(
+      {
+        report: latestPath,
+        timestamped: timestampedPath,
+        analyzed: analyzed.length,
+        total: all.length,
+      },
+      null,
+      2,
+    ),
+  );
+
+  return 0;
+}
+
+export function buildRefineReport(
+  analyzed: Thread[],
+  totalCount: number,
+  generatedAt: string,
+): string {
+  const entries = flattenReviewAnnotations(analyzed);
+  const lines: string[] = [
+    "# refine report",
+    "",
+    `Generated ${generatedAt}.`,
+    "",
+    `${analyzed.length} sessions analyzed (${totalCount} total).`,
+    "",
+    "## Corpus",
+    "",
+    "By primitive:",
+    ...byCount(analyzed, primitiveLabel).map(([label, count]) => `- ${label}: ${count}`),
+    "",
+    "By verdict:",
+    ...byCount(analyzed, verdictLabel).map(([label, count]) => `- ${label}: ${count}`),
+    "",
+    "## Annotations by kind",
+    "",
+  ];
+
+  if (entries.length === 0) {
+    lines.push("No reviewer annotations in the analyzed sessions.", "");
+  } else {
+    for (const [kind, group] of groupByKind(entries)) {
+      lines.push(`### ${kind} (${group.length})`, "");
+      for (const { annotation, session } of group) {
+        const meta = [
+          session.id,
+          primitiveLabel(session),
+          verdictLabel(session),
+          isoWeek(annotation.createdAt),
+        ].join(" · ");
+
+        lines.push(
+          `- "${truncate(annotation.anchor.quote, QUOTE_LIMIT)}": ${truncate(annotation.body, BODY_LIMIT)} · ${meta}`,
+        );
+      }
+      lines.push("");
+    }
+  }
+
+  lines.push("## Weekly volume", "");
+  for (const [week, count] of byKey(
+    entries.map((entry) => entry.annotation),
+    (annotation) => isoWeek(annotation.createdAt),
+  )) {
+    lines.push(`- ${week}: ${count}`);
+  }
+  lines.push(
+    "",
+    "## Next",
+    "",
+    "Group the annotations above into named patterns of three or more members.",
+    "Rank each pattern by how often its members sit on a request-changes or comment verdict.",
+    "Draft one writeback per pattern, routed to a skill, AGENTS.md, CLAUDE.md, or memory.",
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+function hasReviewSignal(session: Thread): boolean {
+  return (
+    session.verdict !== null || session.annotations.some((annotation) => !isAgentNote(annotation))
+  );
+}
+
+function flattenReviewAnnotations(sessions: Thread[]): AnnotatedEntry[] {
+  const entries: AnnotatedEntry[] = [];
+
+  for (const session of sessions) {
+    for (const annotation of session.annotations) {
+      if (!isAgentNote(annotation)) entries.push({ annotation, session });
+    }
+  }
+
+  return entries;
+}
+
+function groupByKind(entries: AnnotatedEntry[]): [string, AnnotatedEntry[]][] {
+  const groups = new Map<string, AnnotatedEntry[]>();
+
+  for (const entry of entries) {
+    const group = groups.get(entry.annotation.kind) ?? [];
+
+    group.push(entry);
+    groups.set(entry.annotation.kind, group);
+  }
+
+  return [...groups.entries()].toSorted(
+    (left, right) => right[1].length - left[1].length || left[0].localeCompare(right[0]),
+  );
+}
+
+function byCount<T>(items: T[], keyOf: (item: T) => string): [string, number][] {
+  return [...tally(items, keyOf).entries()].toSorted(
+    (left, right) => right[1] - left[1] || left[0].localeCompare(right[0]),
+  );
+}
+
+function byKey<T>(items: T[], keyOf: (item: T) => string): [string, number][] {
+  return [...tally(items, keyOf).entries()].toSorted((left, right) =>
+    left[0].localeCompare(right[0]),
+  );
+}
+
+function tally<T>(items: T[], keyOf: (item: T) => string): Map<string, number> {
+  const counts = new Map<string, number>();
+
+  for (const item of items) {
+    const key = keyOf(item);
+
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+
+  return counts;
+}
+
+function primitiveLabel(session: Thread): string {
+  if (session.artifact.type === "diff" && session.artifact.meta.pr) return "pull request";
+
+  return session.artifact.type;
+}
+
+function verdictLabel(session: Thread): string {
+  switch (session.verdict?.kind) {
+    case "approve":
+      return "approve";
+    case "request_changes":
+      return "request changes";
+    case "comment":
+      return "comment";
+    default:
+      return "none";
+  }
+}
+
+function isoWeek(iso: string): string {
+  const date = new Date(iso);
+
+  if (Number.isNaN(date.getTime())) return "undated";
+  const utc = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+  const weekday = utc.getUTCDay() || 7;
+
+  utc.setUTCDate(utc.getUTCDate() + 4 - weekday);
+  const yearStart = new Date(Date.UTC(utc.getUTCFullYear(), 0, 1));
+  const week = Math.ceil(((utc.getTime() - yearStart.getTime()) / (24 * 60 * 60 * 1000) + 1) / 7);
+
+  return `${utc.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+}
+
+function truncate(text: string, max: number): string {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+
+  return collapsed.length > max ? `${collapsed.slice(0, max - 1)}…` : collapsed;
+}
+
+function parseLimit(raw: string | undefined): number {
+  const value = Number(raw);
+
+  return Number.isInteger(value) && value > 0 ? value : DEFAULT_SESSION_LIMIT;
+}
+
+function analysisFingerprint(session: Thread): string {
+  return `${session.revisions.length}:${session.annotations.length}:${session.verdict?.resolvedAt ?? "pending"}`;
+}
+
+function statePath(home: string): string {
+  return join(home, "refine-state.json");
+}
+
+function readState(home: string): Map<string, string> {
+  try {
+    return parseRefineState(JSON.parse(readFileSync(statePath(home), "utf8")));
+  } catch {
+    return new Map();
+  }
+}
+
+function writeState(home: string, analyzed: Map<string, string>): void {
+  const state = { analyzed: Object.fromEntries(analyzed) };
+
+  writeFileSync(statePath(home), JSON.stringify(state, null, 2));
+}