codetrap 0.1.4 → 0.1.6

package/src/lib/session-codec.ts

@@ -0,0 +1,261 @@
+import { basename, join } from "node:path";
+import type {
+  CandidateTrap,
+  SessionIndexEntry,
+  SessionMetadata,
+  SessionNote,
+  SessionNoteCounts,
+} from "../domain/session";
+import { SESSION_NOTE_KINDS } from "../domain/session";
+
+export const SESSIONS_DIR = "sessions";
+export const ACTIVE_SESSION_FILE = "active.json";
+export const SESSION_INDEX_FILE = "index.json";
+export const SESSION_FILE = "session.json";
+export const NOTES_FILE = "implementation-notes.md";
+export const RECAP_FILE = "recap.md";
+export const CANDIDATES_FILE = "candidate-traps.json";
+
+export function createSessionId(goal: string, now: Date, exists: (id: string) => boolean): string {
+  const date = now.toISOString().slice(0, 10);
+  const base = `${date}-${slugify(goal)}`;
+  let candidate = base;
+  let suffix = 2;
+  while (exists(candidate)) {
+    candidate = `${base}-${suffix++}`;
+  }
+  return candidate;
+}
+
+export function slugify(value: string): string {
+  const slug = value
+    .normalize("NFKD")
+    .replace(/[^\w\s-]/g, "")
+    .trim()
+    .toLowerCase()
+    .replace(/[_\s]+/g, "-")
+    .replace(/-+/g, "-")
+    .slice(0, 64)
+    .replace(/^-|-$/g, "");
+  return slug || "session";
+}
+
+export function sessionRelativeDir(id: string): string {
+  return join(".codetrap", SESSIONS_DIR, id);
+}
+
+export function sessionRelativeFile(id: string, file: string): string {
+  return join(sessionRelativeDir(id), file);
+}
+
+export function formatImplementationNotesHeader(session: SessionMetadata): string {
+  return [
+    `# Implementation Notes: ${session.goal}`,
+    "",
+    `Session: ${session.id}`,
+    `Status: ${session.status}`,
+    "",
+    "## Timeline",
+    "",
+  ].join("\n");
+}
+
+export function formatSessionNote(note: SessionNote): string {
+  const lines = [
+    `### ${note.created_at} ${note.kind}`,
+    "",
+    note.text.trim(),
+  ];
+  if (note.source_ref) {
+    lines.push("", `Source ref: ${note.source_ref}`);
+  }
+  if (note.related_files.length > 0) {
+    lines.push("", "Related files:", ...note.related_files.map((file) => `- ${file}`));
+  }
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+export function parseSessionNotes(markdown: string): SessionNote[] {
+  const lines = markdown.split(/\r?\n/);
+  const notes: SessionNote[] = [];
+  let current: { created_at: string; kind: SessionNote["kind"]; lines: string[] } | null = null;
+
+  for (const line of lines) {
+    const match = line.match(/^###\s+(\S+)\s+(\S+)\s*$/);
+    if (match && isSessionNoteKind(match[2])) {
+      if (current) notes.push(parseNoteBlock(current.created_at, current.kind, current.lines));
+      current = { created_at: match[1], kind: match[2], lines: [] };
+      continue;
+    }
+    if (current) current.lines.push(line);
+  }
+
+  if (current) notes.push(parseNoteBlock(current.created_at, current.kind, current.lines));
+  return notes;
+}
+
+export function noteCounts(notes: SessionNote[]): SessionNoteCounts {
+  const counts: SessionNoteCounts = {};
+  for (const note of notes) {
+    counts[note.kind] = (counts[note.kind] ?? 0) + 1;
+  }
+  return counts;
+}
+
+export function formatRecap(
+  session: SessionMetadata,
+  notes: SessionNote[],
+  candidates: CandidateTrap[] = []
+): string {
+  const decisions = notes.filter((note) => note.kind === "decision");
+  const deviations = notes.filter((note) => note.kind === "deviation");
+  const tradeoffs = notes.filter((note) => note.kind === "tradeoff");
+  const failures = notes.filter((note) => note.kind === "failure" || note.kind === "test_failure");
+  const questions = notes.filter((note) => note.kind === "open_question");
+  const observations = notes.filter((note) => note.kind === "observation" || note.kind === "correction" || note.kind === "review");
+
+  return [
+    `# Session Recap: ${session.goal}`,
+    "",
+    "## Goal",
+    "",
+    session.goal,
+    "",
+    "## What Changed",
+    "",
+    formatNoteList(observations, "No implementation observations were captured."),
+    "",
+    "## Decisions",
+    "",
+    formatNoteList(decisions, "No decisions were captured."),
+    "",
+    "## Deviations From Spec",
+    "",
+    formatNoteList(deviations, "No deviations were captured."),
+    "",
+    "## Tradeoffs",
+    "",
+    formatNoteList(tradeoffs, "No tradeoffs were captured."),
+    "",
+    "## Failures And Fixes",
+    "",
+    formatNoteList(failures, "No failures were captured."),
+    "",
+    "## Open Questions",
+    "",
+    formatNoteList(questions, "No open questions were captured."),
+    "",
+    "## Candidate Traps",
+    "",
+    candidates.length > 0
+      ? candidates.map((candidate) => `- ${candidate.id}: ${candidate.trap.title} (${candidate.quality_score.toFixed(2)})`).join("\n")
+      : "No candidate traps were proposed.",
+    "",
+    "## Accepted Traps",
+    "",
+    formatAcceptedCandidates(candidates),
+    "",
+  ].join("\n");
+}
+
+export function recapSummary(session: SessionMetadata, notes: SessionNote[], candidates: CandidateTrap[]): string {
+  const noteCount = notes.length;
+  const candidateCount = candidates.length;
+  return `Captured ${noteCount} note${noteCount === 1 ? "" : "s"} for ${session.goal}; proposed ${candidateCount} candidate trap${candidateCount === 1 ? "" : "s"}.`;
+}
+
+export function sessionIndexEntry(
+  session: SessionMetadata,
+  notes: SessionNote[],
+  candidates: CandidateTrap[],
+  summary: string | null
+): SessionIndexEntry {
+  return {
+    id: session.id,
+    goal: session.goal,
+    status: session.status,
+    created_at: session.created_at,
+    closed_at: session.closed_at,
+    module: session.module,
+    owner: session.owner,
+    note_counts: noteCounts(notes),
+    candidate_count: candidates.length,
+    accepted_count: candidates.filter((candidate) => candidate.status === "accepted").length,
+    summary,
+  };
+}
+
+export function summarizeNoteText(text: string, maxLength = 96): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  if (normalized.length <= maxLength) return normalized;
+  return `${normalized.slice(0, maxLength - 1).trimEnd()}...`;
+}
+
+function parseNoteBlock(created_at: string, kind: SessionNote["kind"], lines: string[]): SessionNote {
+  const textLines: string[] = [];
+  const relatedFiles: string[] = [];
+  let sourceRef: string | null = null;
+  let inRelatedFiles = false;
+
+  for (const line of trimOuterBlankLines(lines)) {
+    const sourceMatch = line.match(/^Source ref:\s*(.+)$/);
+    if (sourceMatch) {
+      sourceRef = sourceMatch[1].trim() || null;
+      inRelatedFiles = false;
+      continue;
+    }
+    if (line.trim() === "Related files:") {
+      inRelatedFiles = true;
+      continue;
+    }
+    if (inRelatedFiles) {
+      const relatedFileMatch = line.match(/^-\s+(.+)$/);
+      if (relatedFileMatch) {
+        relatedFiles.push(relatedFileMatch[1].trim());
+        continue;
+      }
+      inRelatedFiles = false;
+    }
+    textLines.push(line);
+  }
+
+  return {
+    created_at,
+    kind,
+    text: trimOuterBlankLines(textLines).join("\n").trim(),
+    related_files: relatedFiles,
+    source_ref: sourceRef,
+  };
+}
+
+function trimOuterBlankLines(lines: string[]): string[] {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && lines[start].trim() === "") start++;
+  while (end > start && lines[end - 1].trim() === "") end--;
+  return lines.slice(start, end);
+}
+
+function formatNoteList(notes: SessionNote[], empty: string): string {
+  if (notes.length === 0) return empty;
+  return notes.map((note) => `- ${summarizeNoteText(note.text)}${formatRelatedFiles(note.related_files)}`).join("\n");
+}
+
+function formatRelatedFiles(relatedFiles: string[]): string {
+  if (relatedFiles.length === 0) return "";
+  const displayed = relatedFiles.slice(0, 3).map((file) => basename(file)).join(", ");
+  return ` [${displayed}]`;
+}
+
+function formatAcceptedCandidates(candidates: CandidateTrap[]): string {
+  const accepted = candidates.filter((candidate) => candidate.status === "accepted");
+  if (accepted.length === 0) return "No candidate traps have been accepted yet.";
+  return accepted
+    .map((candidate) => `- ${candidate.id}: Trap #${candidate.accepted_trap_id} (${candidate.accepted_scope})`)
+    .join("\n");
+}
+
+function isSessionNoteKind(value: string): value is SessionNote["kind"] {
+  return (SESSION_NOTE_KINDS as readonly string[]).includes(value);
+}

package/src/lib/session-conflicts.ts

@@ -0,0 +1,104 @@
+import type { CandidateTrap } from "../domain/session";
+import type { Trap } from "../domain/trap";
+import type { Scope } from "./constants";
+import type { TrapOperations } from "./trap-operations";
+import { parseTrapPathGlobs, parseTrapTags } from "./trap-json-fields";
+import { globMatchesPath, normalizePath, trapAppliesToPath } from "./trap-scope-match";
+
+export interface CandidateConflict {
+  trap_id: number;
+  scope: Scope;
+  title: string;
+  context: string;
+  fix: string;
+  reason: string;
+}
+
+export async function findCandidateConflicts(
+  candidate: CandidateTrap,
+  operations: TrapOperations
+): Promise<CandidateConflict[]> {
+  const query = conflictQuery(candidate);
+  if (!query) return [];
+
+  const cards = await operations.searchTrapCards({
+    query,
+    scope: candidate.trap.scope,
+    status: "active",
+    limit: 3,
+    mode: "fts",
+  });
+
+  const conflicts: CandidateConflict[] = [];
+  for (const card of cards) {
+    const details = operations.getTrapDetails(card.trap_id, card.scope);
+    if (!details || details.trap.status !== "active") continue;
+    const reason = conflictReason(candidate, details.trap);
+    if (!reason) continue;
+    conflicts.push({
+      trap_id: details.trap.id,
+      scope: details.scope,
+      title: details.trap.title,
+      context: details.trap.context,
+      fix: details.trap.fix,
+      reason,
+    });
+  }
+  return conflicts;
+}
+
+function conflictQuery(candidate: CandidateTrap): string {
+  return [
+    candidate.trap.title,
+    ...(candidate.trap.tags ?? []),
+    candidate.trap.module,
+  ].filter(Boolean).join(" ").trim();
+}
+
+function conflictReason(candidate: CandidateTrap, existing: Trap): string | null {
+  const sameModule = Boolean(candidate.trap.module && existing.module === candidate.trap.module);
+  if (sameModule) return "same module";
+
+  if (pathScopesOverlap(candidate, existing)) return "overlapping path scope";
+
+  const candidateTags = candidate.trap.tags ?? [];
+  const existingTags = parseTrapTags(existing.tags);
+  if (intersects(candidateTags, existingTags) && titleOverlap(candidate.trap.title, existing.title) >= 2) {
+    return "similar title and tags";
+  }
+
+  return null;
+}
+
+function intersects(left: string[], right: string[]): boolean {
+  const rightSet = new Set(right.map((value) => value.toLowerCase()));
+  return left.some((value) => rightSet.has(value.toLowerCase()));
+}
+
+function pathScopesOverlap(candidate: CandidateTrap, existing: Trap): boolean {
+  const candidatePaths = candidate.trap.path_globs ?? [];
+  const existingPaths = parseTrapPathGlobs(existing.path_globs);
+  if (candidatePaths.length === 0 || existingPaths.length === 0) return false;
+
+  return candidatePaths.some((candidatePath) =>
+    trapAppliesToPath(existing, candidatePath)
+      || existingPaths.some((existingPath) => pathGlobsMayOverlap(candidatePath, existingPath))
+  );
+}
+
+function pathGlobsMayOverlap(left: string, right: string): boolean {
+  const normalizedLeft = normalizePath(left);
+  const normalizedRight = normalizePath(right);
+  return normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+    || globMatchesPath(normalizedLeft, normalizedRight)
+    || globMatchesPath(normalizedRight, normalizedLeft);
+}
+
+function titleOverlap(left: string, right: string): number {
+  const leftTokens = new Set(tokens(left));
+  return tokens(right).filter((token) => leftTokens.has(token)).length;
+}
+
+function tokens(value: string): string[] {
+  return value.toLowerCase().match(/[a-z0-9_]+/g) ?? [];
+}

package/src/lib/session-operations.ts

@@ -0,0 +1,214 @@
+import type { CandidateTrap } from "../domain/session";
+import { buildTrapInput } from "../domain/trap";
+import type { TrapOperations } from "./trap-operations";
+import { findCandidateConflicts, type CandidateConflict } from "./session-conflicts";
+import type {
+  AcceptCandidateResult,
+  AddSessionNoteArgs,
+  CloseSessionResult,
+  SessionStore,
+  StartSessionArgs,
+} from "./session-store";
+
+export type SessionAcceptRequest = {
+  candidateId: string;
+  sessionId?: string;
+  edit?: Record<string, unknown>;
+  supersedesId?: number;
+  acceptAnyway?: boolean;
+};
+
+export type SessionSaveCandidateRequest = {
+  candidateId: string;
+  sessionId?: string;
+  edit: Record<string, unknown>;
+};
+
+export type SessionRejectRequest = {
+  candidateId: string;
+  sessionId?: string;
+  reason?: string | null;
+};
+
+export type SessionConflictResult = {
+  success: false;
+  session_id: string;
+  candidate_id: string;
+  possible_conflicts: CandidateConflict[];
+};
+
+export type SessionAcceptSuccess = AcceptCandidateResult & {
+  success: true;
+};
+
+export type SessionAcceptResult = SessionAcceptSuccess | SessionConflictResult;
+
+export class SessionOperations {
+  constructor(
+    private readonly sessions: SessionStore,
+    private readonly traps: TrapOperations
+  ) {}
+
+  startSession(args: StartSessionArgs) {
+    return this.sessions.startSession(args);
+  }
+
+  addNote(args: AddSessionNoteArgs) {
+    return this.sessions.addNote(args);
+  }
+
+  status() {
+    return this.sessions.status();
+  }
+
+  listSessions(args: { status?: string; limit?: number } = {}) {
+    return this.sessions.listSessions(args);
+  }
+
+  showSession(id: string) {
+    return this.sessions.showSession(id);
+  }
+
+  summarizeNotes(id?: string) {
+    return this.sessions.summarizeNotes(id);
+  }
+
+  closeSession(id: string | undefined, proposeTraps: boolean): CloseSessionResult {
+    return this.sessions.closeSession(id, proposeTraps);
+  }
+
+  candidateDocument(id?: string) {
+    return this.sessions.candidateDocument(id);
+  }
+
+  getCandidate(candidateId: string, sessionId?: string) {
+    return this.sessions.getCandidate(candidateId, sessionId);
+  }
+
+  saveCandidate(request: SessionSaveCandidateRequest) {
+    const { session, candidate } = this.sessions.getCandidate(request.candidateId, request.sessionId);
+    const editedCandidate = candidateWithTrapEdits(candidate, request.edit);
+    return this.sessions.saveCandidateTrap(editedCandidate.id, {
+      sessionId: session.id,
+      trap: editedCandidate.trap,
+    });
+  }
+
+  async acceptCandidate(request: SessionAcceptRequest): Promise<SessionAcceptResult> {
+    const { session, candidate } = this.sessions.getCandidate(request.candidateId, request.sessionId);
+    const editedCandidate = candidateWithTrapEdits(candidate, request.edit);
+    const supersedesId = request.supersedesId;
+    const conflicts = await findCandidateConflicts(editedCandidate, this.traps);
+    if (conflicts.length > 0 && supersedesId === undefined && request.acceptAnyway !== true) {
+      const checked = this.sessions.recordCandidateConflictCheck(candidate.id, {
+        sessionId: session.id,
+        trap: editedCandidate.trap,
+        conflictStatus: "possible",
+        suggestedAction: "supersede",
+      });
+      return {
+        success: false,
+        session_id: checked.session.id,
+        candidate_id: checked.candidate.id,
+        possible_conflicts: conflicts,
+      };
+    }
+
+    const trap = editedCandidate.trap;
+    if (supersedesId !== undefined && !this.traps.getTrapDetails(supersedesId, String(trap.scope))) {
+      throw new Error(`Trap #${supersedesId} not found in ${String(trap.scope)} scope.`);
+    }
+
+    const added = this.traps.addTrap({ ...trap });
+    const evidence = this.traps.addTrapEvidence(added.id, {
+      source_type: "conversation",
+      source_ref: `session:${session.id}`,
+      related_files: candidateRelatedFiles(editedCandidate),
+      note: `Accepted from session candidate ${editedCandidate.id}`,
+    }, added.scope);
+    if (!evidence.success) throw new Error(`Failed to attach evidence to trap #${added.id}.`);
+
+    if (supersedesId !== undefined) {
+      const supersede = this.traps.supersedeTrap(supersedesId, added.id, added.scope);
+      if (!supersede.success) throw new Error(`Trap #${supersedesId} could not be superseded by trap #${added.id}.`);
+    }
+
+    return {
+      success: true,
+      ...this.sessions.acceptCandidate(editedCandidate.id, {
+        sessionId: session.id,
+        trap,
+        trapId: added.id,
+        scope: added.scope,
+        evidenceId: evidence.evidence_id,
+        supersededId: supersedesId ?? null,
+        conflictChecked: true,
+        conflictStatus: supersedesId !== undefined ? "confirmed" : conflicts.length > 0 ? "possible" : "none",
+        suggestedAction: supersedesId !== undefined ? "supersede" : "accept",
+      }),
+    };
+  }
+
+  rejectCandidate(request: SessionRejectRequest) {
+    return this.sessions.rejectCandidate(request.candidateId, {
+      sessionId: request.sessionId,
+      reason: request.reason,
+    });
+  }
+}
+
+function candidateWithTrapEdits(candidate: CandidateTrap, edit: Record<string, unknown> | undefined): CandidateTrap {
+  return {
+    ...candidate,
+    trap: normalizeCandidateTrap({
+      ...candidate.trap,
+      ...trapEdits(edit),
+    }) as CandidateTrap["trap"],
+  };
+}
+
+function normalizeCandidateTrap(args: Record<string, unknown>) {
+  return buildTrapInput({
+    ...args,
+    tags: stringArray(args.tags),
+    path_globs: stringArray(args.path_globs),
+    module: optionalText(args.module),
+    owner: optionalText(args.owner),
+    before_code: optionalText(args.before_code),
+    after_code: optionalText(args.after_code),
+  });
+}
+
+function stringArray(value: unknown): string[] | undefined {
+  if (Array.isArray(value)) return value.map(String).map((item) => item.trim()).filter(Boolean);
+  if (typeof value === "string") {
+    const values = value.split(",").map((item) => item.trim()).filter(Boolean);
+    return values.length > 0 ? values : undefined;
+  }
+  return undefined;
+}
+
+function optionalText(value: unknown): string | null | undefined {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  const text = String(value).trim();
+  return text ? text : null;
+}
+
+function trapEdits(edit: Record<string, unknown> | undefined): Record<string, unknown> {
+  if (!edit) return {};
+  const nested = edit.trap;
+  return isRecord(nested) ? nested : edit;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function candidateRelatedFiles(candidate: CandidateTrap): string[] {
+  return uniqueStrings(candidate.evidence.flatMap((evidence) => evidence.related_files ?? []));
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}