codetrap 0.1.4 → 0.1.6

package/src/lib/session-store.ts

@@ -0,0 +1,503 @@
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { CandidateTrap, CandidateTrapDocument, SessionIndexDocument, SessionMetadata, SessionNote } from "../domain/session";
+import { parseSessionNoteKind, SESSION_VERSION } from "../domain/session";
+import { CODETRAP_DIR } from "./constants";
+import {
+  ACTIVE_SESSION_FILE,
+  CANDIDATES_FILE,
+  createSessionId,
+  formatImplementationNotesHeader,
+  formatRecap,
+  formatSessionNote,
+  NOTES_FILE,
+  noteCounts,
+  parseSessionNotes,
+  recapSummary,
+  RECAP_FILE,
+  sessionIndexEntry,
+  SESSION_FILE,
+  SESSION_INDEX_FILE,
+  sessionRelativeFile,
+  SESSIONS_DIR,
+} from "./session-codec";
+import { proposeCandidateTraps } from "./session-capture";
+import { scoreCandidateTrap } from "./trap-quality";
+
+export interface StartSessionArgs {
+  goal: string;
+  specRef?: string | null;
+  module?: string | null;
+  owner?: string | null;
+}
+
+export interface AddSessionNoteArgs {
+  kind?: string;
+  text: string;
+  relatedFiles?: string[];
+  sourceRef?: string | null;
+}
+
+export interface CloseSessionResult {
+  session: SessionMetadata;
+  recap_path: string;
+  candidate_count: number;
+  traps_written: number;
+}
+
+export interface AcceptCandidateResult {
+  session: SessionMetadata;
+  candidate: CandidateTrap;
+  trap_id: number;
+  scope: string;
+  evidence_id: number | null;
+  superseded_id: number | null;
+}
+
+export class SessionStore {
+  constructor(private readonly projectRoot: string) {}
+
+  startSession(args: StartSessionArgs, now = new Date()): SessionMetadata {
+    const active = this.activeSession();
+    if (active) {
+      throw new Error(`Session ${active.id} is already active. Close it before starting another session.`);
+    }
+
+    const goal = args.goal.trim();
+    if (!goal) throw new Error("Session goal is required.");
+
+    this.ensureSessionsDir();
+    const id = createSessionId(goal, now, (candidate) => existsSync(this.sessionDir(candidate)));
+    const createdAt = now.toISOString();
+    const session: SessionMetadata = {
+      version: SESSION_VERSION,
+      id,
+      goal,
+      status: "active",
+      created_at: createdAt,
+      updated_at: createdAt,
+      closed_at: null,
+      scope: "project",
+      project_path: this.projectRoot,
+      module: args.module ?? null,
+      owner: args.owner ?? null,
+      spec_ref: args.specRef ?? null,
+      notes_path: NOTES_FILE,
+      recap_path: RECAP_FILE,
+      candidate_traps_path: CANDIDATES_FILE,
+    };
+
+    mkdirSync(this.sessionDir(id), { recursive: true });
+    this.writeSession(session);
+    writeFileSync(this.notesPath(id), formatImplementationNotesHeader(session));
+    this.writeIndexEntry(session, [], [], null);
+    this.writeActive(id);
+    return session;
+  }
+
+  addNote(args: AddSessionNoteArgs, now = new Date()): { session: SessionMetadata; note: SessionNote; notes_path: string } {
+    const session = this.requireActiveSession();
+    const text = args.text.trim();
+    if (!text) throw new Error("Session note text is required.");
+
+    const note: SessionNote = {
+      created_at: now.toISOString(),
+      kind: parseSessionNoteKind(args.kind),
+      text,
+      related_files: uniqueStrings(args.relatedFiles ?? []),
+      source_ref: args.sourceRef ?? null,
+    };
+
+    appendFileSync(this.notesPath(session.id), formatSessionNote(note));
+    const updated = { ...session, updated_at: note.created_at };
+    this.writeSession(updated);
+    this.writeIndexEntry(updated, this.readNotes(updated.id), this.readCandidateDocument(updated.id).candidates, null);
+    return {
+      session: updated,
+      note,
+      notes_path: sessionRelativeFile(updated.id, NOTES_FILE),
+    };
+  }
+
+  status(): { active_session_id: string | null; session: SessionMetadata | null } {
+    const active = this.activeSession();
+    return {
+      active_session_id: active?.id ?? null,
+      session: active,
+    };
+  }
+
+  listSessions(args: { status?: string; limit?: number } = {}) {
+    const status = args.status ?? "all";
+    if (!["active", "closed", "all"].includes(status)) {
+      throw new Error("Invalid session status. Expected active, closed, or all.");
+    }
+    const sessions = this.readIndex().sessions
+      .filter((entry) => status === "all" || entry.status === status)
+      .sort((a, b) => b.created_at.localeCompare(a.created_at));
+    return typeof args.limit === "number" ? sessions.slice(0, args.limit) : sessions;
+  }
+
+  getSession(id: string): SessionMetadata {
+    return this.requireSession(id);
+  }
+
+  showSession(id: string): { session: SessionMetadata; recap: string | null; notes_path: string; session_dir: string } {
+    const session = this.requireSession(id);
+    return {
+      session,
+      recap: this.readOptionalText(this.recapPath(id)),
+      notes_path: sessionRelativeFile(id, NOTES_FILE),
+      session_dir: join(".codetrap", SESSIONS_DIR, id),
+    };
+  }
+
+  summarizeNotes(id?: string): {
+    session: SessionMetadata;
+    notes_path: string;
+    content: string;
+    notes: SessionNote[];
+    note_counts: ReturnType<typeof noteCounts>;
+    latest_notes: { created_at: string; kind: string; text: string; related_files: string[] }[];
+  } {
+    const session = this.requireSession(this.resolveSessionId(id));
+    const content = this.readOptionalText(this.notesPath(session.id)) ?? "";
+    const notes = parseSessionNotes(content);
+    return {
+      session,
+      notes_path: sessionRelativeFile(session.id, NOTES_FILE),
+      content,
+      notes,
+      note_counts: noteCounts(notes),
+      latest_notes: notes.slice(-3).reverse().map((note) => ({
+        created_at: note.created_at,
+        kind: note.kind,
+        text: note.text,
+        related_files: note.related_files,
+      })),
+    };
+  }
+
+  closeSession(id: string | undefined, proposeTraps: boolean, now = new Date()): CloseSessionResult {
+    const session = this.requireSession(this.resolveSessionId(id, { requireActive: id === undefined }));
+    if (session.status === "closed") throw new Error(`Session ${session.id} is already closed.`);
+
+    const closedAt = now.toISOString();
+    const notes = this.readNotes(session.id);
+    const candidates = proposeTraps ? proposeCandidateTraps(session, notes) : this.readCandidateDocument(session.id).candidates;
+    if (proposeTraps) this.writeCandidateDocument(session.id, candidates);
+
+    const updated = {
+      ...session,
+      status: "closed" as const,
+      closed_at: closedAt,
+      updated_at: closedAt,
+    };
+    this.writeSession(updated);
+    writeFileSync(this.recapPath(updated.id), formatRecap(updated, notes, candidates));
+    this.writeIndexEntry(updated, notes, candidates, recapSummary(updated, notes, candidates));
+    if (this.readActive()?.active_session_id === updated.id) this.clearActive();
+
+    return {
+      session: updated,
+      recap_path: sessionRelativeFile(updated.id, RECAP_FILE),
+      candidate_count: candidates.length,
+      traps_written: 0,
+    };
+  }
+
+  candidateDocument(id?: string): CandidateTrapDocument {
+    const sessionId = this.resolveSessionId(id);
+    return this.readCandidateDocument(sessionId);
+  }
+
+  getCandidate(candidateId: string, sessionId?: string): { session: SessionMetadata; candidate: CandidateTrap } {
+    const resolvedSessionId = this.resolveSessionId(sessionId);
+    const session = this.requireSession(resolvedSessionId);
+    const candidate = this.findCandidate(resolvedSessionId, candidateId);
+    return { session, candidate };
+  }
+
+  recordCandidateConflictCheck(
+    candidateId: string,
+    args: {
+      sessionId?: string;
+      trap?: CandidateTrap["trap"];
+      conflictStatus: CandidateTrap["quality"]["conflict_status"];
+      suggestedAction: CandidateTrap["quality"]["suggested_action"];
+    }
+  ): { session: SessionMetadata; candidate: CandidateTrap } {
+    const sessionId = this.resolveSessionId(args.sessionId);
+    const session = this.requireSession(sessionId);
+    const document = this.readCandidateDocument(sessionId);
+    const candidate = document.candidates.find((item) => item.id === candidateId);
+    if (!candidate) throw new Error(`Candidate ${candidateId} not found in session ${sessionId}.`);
+    if (candidate.status !== "proposed") throw new Error(`Candidate ${candidateId} is already ${candidate.status}.`);
+
+    if (args.trap) candidate.trap = args.trap;
+    candidate.quality.conflict_checked = true;
+    candidate.quality.conflict_status = args.conflictStatus;
+    candidate.quality.suggested_action = args.suggestedAction;
+    this.writeCandidateDocument(session.id, document.candidates);
+    this.refreshSessionSummaries(session.id);
+    return { session, candidate };
+  }
+
+  saveCandidateTrap(
+    candidateId: string,
+    args: {
+      sessionId?: string;
+      trap: CandidateTrap["trap"];
+    }
+  ): { session: SessionMetadata; candidate: CandidateTrap } {
+    const sessionId = this.resolveSessionId(args.sessionId);
+    const session = this.requireSession(sessionId);
+    const document = this.readCandidateDocument(sessionId);
+    const candidate = document.candidates.find((item) => item.id === candidateId);
+    if (!candidate) throw new Error(`Candidate ${candidateId} not found in session ${sessionId}.`);
+    if (candidate.status !== "proposed") throw new Error(`Candidate ${candidateId} is already ${candidate.status}.`);
+
+    const scored = scoreCandidateTrap({ trap: args.trap, evidence: candidate.evidence });
+    candidate.trap = args.trap;
+    candidate.quality_score = scored.score;
+    candidate.quality = scored.quality;
+    this.writeCandidateDocument(session.id, document.candidates);
+    this.refreshSessionSummaries(session.id);
+    return { session, candidate };
+  }
+
+  acceptCandidate(
+    candidateId: string,
+    args: {
+      sessionId?: string;
+      trap?: CandidateTrap["trap"];
+      trapId: number;
+      scope: string;
+      evidenceId: number | null;
+      supersededId?: number | null;
+      conflictChecked?: boolean;
+      conflictStatus?: CandidateTrap["quality"]["conflict_status"];
+      suggestedAction?: CandidateTrap["quality"]["suggested_action"];
+    },
+    now = new Date()
+  ): AcceptCandidateResult {
+    const sessionId = this.resolveSessionId(args.sessionId);
+    const session = this.requireSession(sessionId);
+    const document = this.readCandidateDocument(sessionId);
+    const candidate = document.candidates.find((item) => item.id === candidateId);
+    if (!candidate) throw new Error(`Candidate ${candidateId} not found in session ${sessionId}.`);
+    if (candidate.status !== "proposed") throw new Error(`Candidate ${candidateId} is already ${candidate.status}.`);
+
+    if (args.trap) candidate.trap = args.trap;
+    candidate.status = "accepted";
+    candidate.accepted_trap_id = args.trapId;
+    candidate.accepted_scope = args.scope === "project" ? "project" : "global";
+    candidate.accepted_at = now.toISOString();
+    candidate.quality.conflict_checked = args.conflictChecked ?? candidate.quality.conflict_checked;
+    candidate.quality.conflict_status = args.conflictStatus ?? candidate.quality.conflict_status;
+    candidate.quality.suggested_action = args.suggestedAction ?? candidate.quality.suggested_action;
+    this.writeCandidateDocument(session.id, document.candidates);
+    this.refreshSessionSummaries(session.id);
+
+    return {
+      session,
+      candidate,
+      trap_id: args.trapId,
+      scope: args.scope,
+      evidence_id: args.evidenceId,
+      superseded_id: args.supersededId ?? null,
+    };
+  }
+
+  rejectCandidate(
+    candidateId: string,
+    args: { sessionId?: string; reason?: string | null },
+    now = new Date()
+  ): { session: SessionMetadata; candidate: CandidateTrap } {
+    const sessionId = this.resolveSessionId(args.sessionId);
+    const session = this.requireSession(sessionId);
+    const document = this.readCandidateDocument(sessionId);
+    const candidate = document.candidates.find((item) => item.id === candidateId);
+    if (!candidate) throw new Error(`Candidate ${candidateId} not found in session ${sessionId}.`);
+    if (candidate.status !== "proposed") throw new Error(`Candidate ${candidateId} is already ${candidate.status}.`);
+
+    candidate.status = "rejected";
+    candidate.rejected_at = now.toISOString();
+    if (args.reason) candidate.rejection_reason = args.reason;
+    this.writeCandidateDocument(session.id, document.candidates);
+    this.refreshSessionSummaries(session.id);
+    return { session, candidate };
+  }
+
+  readNotes(id: string): SessionNote[] {
+    return parseSessionNotes(this.readOptionalText(this.notesPath(id)) ?? "");
+  }
+
+  private activeSession(): SessionMetadata | null {
+    const active = this.readActive();
+    if (active?.active_session_id) {
+      const session = this.getSessionOrNull(active.active_session_id);
+      if (session?.status === "active") return session;
+      this.clearActive();
+    }
+    return this.readIndex().sessions
+      .filter((entry) => entry.status === "active")
+      .sort((a, b) => b.created_at.localeCompare(a.created_at))
+      .map((entry) => this.getSessionOrNull(entry.id))
+      .find((session): session is SessionMetadata => session !== null) ?? null;
+  }
+
+  private resolveSessionId(id?: string, opts: { requireActive?: boolean } = {}): string {
+    if (id) return id;
+    const active = this.activeSession();
+    if (active) return active.id;
+    if (opts.requireActive) throw new Error("No active session. Start one with `codetrap session start <goal>`.");
+    const latest = this.listSessions({ status: "all", limit: 1 })[0];
+    if (!latest) throw new Error("No sessions found.");
+    return latest.id;
+  }
+
+  private requireActiveSession(): SessionMetadata {
+    const active = this.activeSession();
+    if (!active) throw new Error("No active session. Start one with `codetrap session start <goal>`.");
+    return active;
+  }
+
+  private requireSession(id: string): SessionMetadata {
+    const session = this.getSessionOrNull(id);
+    if (!session) throw new Error(`Session ${id} not found.`);
+    return session;
+  }
+
+  private getSessionOrNull(id: string): SessionMetadata | null {
+    const path = this.sessionJsonPath(id);
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf-8")) as SessionMetadata;
+  }
+
+  private findCandidate(sessionId: string, candidateId: string): CandidateTrap {
+    const candidate = this.readCandidateDocument(sessionId).candidates.find((item) => item.id === candidateId);
+    if (!candidate) throw new Error(`Candidate ${candidateId} not found in session ${sessionId}.`);
+    return candidate;
+  }
+
+  private readCandidateDocument(id: string): CandidateTrapDocument {
+    const path = this.candidatesPath(id);
+    if (!existsSync(path)) {
+      return { version: SESSION_VERSION, session_id: id, candidates: [] };
+    }
+    return JSON.parse(readFileSync(path, "utf-8")) as CandidateTrapDocument;
+  }
+
+  private writeCandidateDocument(id: string, candidates: CandidateTrap[]): void {
+    writeFileSync(this.candidatesPath(id), `${JSON.stringify({
+      version: SESSION_VERSION,
+      session_id: id,
+      candidates,
+    } satisfies CandidateTrapDocument, null, 2)}\n`);
+  }
+
+  private refreshSessionSummaries(id: string): void {
+    const session = this.requireSession(id);
+    const notes = this.readNotes(id);
+    const candidates = this.readCandidateDocument(id).candidates;
+    writeFileSync(this.recapPath(id), formatRecap(session, notes, candidates));
+    this.writeIndexEntry(session, notes, candidates, recapSummary(session, notes, candidates));
+  }
+
+  private writeSession(session: SessionMetadata): void {
+    writeFileSync(this.sessionJsonPath(session.id), `${JSON.stringify(session, null, 2)}\n`);
+  }
+
+  private readIndex(): SessionIndexDocument {
+    const path = this.indexPath();
+    if (!existsSync(path)) return { version: SESSION_VERSION, sessions: [] };
+    return JSON.parse(readFileSync(path, "utf-8")) as SessionIndexDocument;
+  }
+
+  private writeIndexEntry(
+    session: SessionMetadata,
+    notes: SessionNote[],
+    candidates: CandidateTrap[],
+    summary: string | null
+  ): void {
+    this.ensureSessionsDir();
+    const index = this.readIndex();
+    const existing = index.sessions.find((entry) => entry.id === session.id);
+    const entry = sessionIndexEntry(session, notes, candidates, summary ?? existing?.summary ?? null);
+    const sessions = [entry, ...index.sessions.filter((item) => item.id !== session.id)]
+      .sort((a, b) => b.created_at.localeCompare(a.created_at));
+    writeFileSync(this.indexPath(), `${JSON.stringify({ version: SESSION_VERSION, sessions } satisfies SessionIndexDocument, null, 2)}\n`);
+  }
+
+  private readActive(): { active_session_id: string | null; updated_at: string } | null {
+    const path = this.activePath();
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf-8")) as { active_session_id: string | null; updated_at: string };
+  }
+
+  private writeActive(id: string): void {
+    writeFileSync(this.activePath(), `${JSON.stringify({
+      active_session_id: id,
+      updated_at: new Date().toISOString(),
+    }, null, 2)}\n`);
+  }
+
+  private clearActive(): void {
+    this.ensureSessionsDir();
+    writeFileSync(this.activePath(), `${JSON.stringify({
+      active_session_id: null,
+      updated_at: new Date().toISOString(),
+    }, null, 2)}\n`);
+  }
+
+  private readOptionalText(path: string): string | null {
+    return existsSync(path) ? readFileSync(path, "utf-8") : null;
+  }
+
+  private ensureSessionsDir(): void {
+    mkdirSync(this.sessionsDir(), { recursive: true });
+  }
+
+  private sessionsDir(): string {
+    return join(this.projectRoot, CODETRAP_DIR, SESSIONS_DIR);
+  }
+
+  private sessionDir(id: string): string {
+    return join(this.sessionsDir(), id);
+  }
+
+  private activePath(): string {
+    return join(this.sessionsDir(), ACTIVE_SESSION_FILE);
+  }
+
+  private indexPath(): string {
+    return join(this.sessionsDir(), SESSION_INDEX_FILE);
+  }
+
+  private sessionJsonPath(id: string): string {
+    return join(this.sessionDir(id), SESSION_FILE);
+  }
+
+  private notesPath(id: string): string {
+    return join(this.sessionDir(id), NOTES_FILE);
+  }
+
+  private recapPath(id: string): string {
+    return join(this.sessionDir(id), RECAP_FILE);
+  }
+
+  private candidatesPath(id: string): string {
+    return join(this.sessionDir(id), CANDIDATES_FILE);
+  }
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}

package/src/lib/trap-quality.ts

@@ -0,0 +1,111 @@
+import type { CandidateQuality, CandidateTrap } from "../domain/session";
+
+type CandidateDraft = Pick<CandidateTrap, "trap" | "evidence">;
+
+export function scoreCandidateTrap(candidate: CandidateDraft): { score: number; quality: CandidateQuality } {
+  const trap = candidate.trap;
+  const evidenceCount = candidate.evidence.length;
+  const hasClearTrigger = hasMeaningfulText(trap.context) && hasTriggerLanguage(trap.context);
+  const hasClearMistake = hasMeaningfulText(trap.mistake);
+  const hasActionableFix = hasMeaningfulText(trap.fix) && hasActionLanguage(trap.fix);
+  const futureReuseLikely = hasFutureReuseSignal(candidate);
+  const properScope = trap.scope === "global" || hasSpecificScope(candidate);
+  const notTooBroad = !isTooBroad(candidate);
+
+  const warnings: string[] = [];
+  if (!hasClearTrigger) warnings.push("context does not clearly describe when the trap applies");
+  if (!hasClearMistake) warnings.push("mistake is not specific enough");
+  if (!hasActionableFix) warnings.push("fix is not actionable enough");
+  if (!futureReuseLikely) warnings.push("future reuse is unclear");
+  if (!properScope) warnings.push("scope is too loose for a project trap");
+  if (!notTooBroad) warnings.push("candidate reads like a broad reminder rather than a durable trap");
+  if (evidenceCount === 0) warnings.push("candidate has no evidence");
+
+  const score =
+    (hasClearTrigger ? 0.2 : 0) +
+    (hasClearMistake ? 0.2 : 0) +
+    (hasActionableFix ? 0.2 : 0) +
+    (futureReuseLikely ? 0.15 : 0) +
+    (properScope ? 0.1 : 0) +
+    (evidenceCount > 0 ? 0.1 : 0) +
+    (notTooBroad ? 0.05 : 0);
+
+  return {
+    score: roundScore(score),
+    quality: {
+      has_clear_trigger: hasClearTrigger,
+      has_clear_mistake: hasClearMistake,
+      has_actionable_fix: hasActionableFix,
+      not_too_broad: notTooBroad,
+      future_reuse_likely: futureReuseLikely,
+      proper_scope: properScope,
+      evidence_count: evidenceCount,
+      conflict_checked: false,
+      conflict_status: "none",
+      staleness_risk: "low",
+      suggested_action: suggestedAction(score),
+      warnings,
+    },
+  };
+}
+
+function hasMeaningfulText(value: string | undefined): boolean {
+  return typeof value === "string" && value.replace(/\s+/g, " ").trim().length >= 24;
+}
+
+function hasTriggerLanguage(value: string): boolean {
+  const normalized = value.toLowerCase();
+  return /\bwhen\b|\bwhile\b|\bduring\b|\bif\b/.test(normalized) || /当|如果|处理|实现|修改/.test(value);
+}
+
+function hasActionLanguage(value: string): boolean {
+  const normalized = value.toLowerCase();
+  return /\buse\b|\bavoid\b|\bprefer\b|\bkeep\b|\bcheck\b|\bcall\b|\bwrite\b|\badd\b|\bverify\b/.test(normalized)
+    || /使用|避免|优先|检查|验证|改用|保留|调用/.test(value);
+}
+
+function hasFutureReuseSignal(candidate: CandidateDraft): boolean {
+  const tags = candidate.trap.tags ?? [];
+  return tags.length > 0
+    || (candidate.trap.path_globs?.length ?? 0) > 0
+    || Boolean(candidate.trap.module)
+    || Boolean(candidate.trap.owner);
+}
+
+function hasSpecificScope(candidate: CandidateDraft): boolean {
+  return (candidate.trap.path_globs?.length ?? 0) > 0
+    || Boolean(candidate.trap.module)
+    || Boolean(candidate.trap.owner)
+    || candidate.evidence.some((evidence) => (evidence.related_files?.length ?? 0) > 0);
+}
+
+function isTooBroad(candidate: CandidateDraft): boolean {
+  const combined = [
+    candidate.trap.title,
+    candidate.trap.context,
+    candidate.trap.mistake,
+    candidate.trap.fix,
+  ].join(" ").toLowerCase();
+
+  const broadPhrases = [
+    "read the docs",
+    "write better code",
+    "be careful",
+    "check everything",
+    "always test",
+    "先看文档",
+    "小心",
+    "写好代码",
+  ];
+  return broadPhrases.some((phrase) => combined.includes(phrase));
+}
+
+function roundScore(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function suggestedAction(score: number): CandidateQuality["suggested_action"] {
+  if (score >= 0.8) return "accept";
+  if (score >= 0.6) return "edit";
+  return "reject";
+}

package/src/lib/trap-scope-match.ts

@@ -46,7 +46,7 @@ export function normalizePath(path: string): string {
   return path.replace(/\\/g, "/").replace(/^\.\//, "");
 }
 
-function globMatchesPath(glob: string, path: string): boolean {
+export function globMatchesPath(glob: string, path: string): boolean {
   const normalizedGlob = normalizePath(glob);
   return new RegExp(`^${globToRegExp(normalizedGlob)}$`).test(path);
 }