codetrap 0.1.5 → 0.1.7

package/src/domain/session.ts

@@ -0,0 +1,119 @@
+import type { TrapEvidenceInput, TrapInput } from "./trap";
+import type { Scope } from "../lib/constants";
+
+export const SESSION_VERSION = 1;
+
+export const SESSION_STATUSES = ["active", "closed"] as const;
+export type SessionStatus = (typeof SESSION_STATUSES)[number];
+
+export const SESSION_NOTE_KINDS = [
+  "decision",
+  "deviation",
+  "tradeoff",
+  "open_question",
+  "failure",
+  "test_failure",
+  "correction",
+  "review",
+  "observation",
+] as const;
+
+export type SessionNoteKind = (typeof SESSION_NOTE_KINDS)[number];
+
+export const CANDIDATE_STATUSES = ["proposed", "accepted", "rejected"] as const;
+export type CandidateStatus = (typeof CANDIDATE_STATUSES)[number];
+
+export interface SessionMetadata {
+  version: typeof SESSION_VERSION;
+  id: string;
+  goal: string;
+  status: SessionStatus;
+  created_at: string;
+  updated_at: string;
+  closed_at: string | null;
+  scope: Scope;
+  project_path: string;
+  module: string | null;
+  owner: string | null;
+  spec_ref: string | null;
+  notes_path: string;
+  recap_path: string;
+  candidate_traps_path: string;
+}
+
+export interface SessionNote {
+  created_at: string;
+  kind: SessionNoteKind;
+  text: string;
+  related_files: string[];
+  source_ref: string | null;
+}
+
+export type SessionNoteCounts = Partial<Record<SessionNoteKind, number>>;
+
+export interface SessionIndexEntry {
+  id: string;
+  goal: string;
+  status: SessionStatus;
+  created_at: string;
+  closed_at: string | null;
+  module: string | null;
+  owner: string | null;
+  note_counts: SessionNoteCounts;
+  candidate_count: number;
+  accepted_count: number;
+  summary: string | null;
+}
+
+export interface SessionIndexDocument {
+  version: typeof SESSION_VERSION;
+  sessions: SessionIndexEntry[];
+}
+
+export interface ActiveSessionDocument {
+  active_session_id: string | null;
+  updated_at: string;
+}
+
+export interface CandidateQuality {
+  has_clear_trigger: boolean;
+  has_clear_mistake: boolean;
+  has_actionable_fix: boolean;
+  not_too_broad: boolean;
+  future_reuse_likely: boolean;
+  proper_scope: boolean;
+  evidence_count: number;
+  conflict_checked: boolean;
+  conflict_status: "none" | "possible" | "confirmed";
+  staleness_risk: "low" | "medium" | "high";
+  suggested_action: "accept" | "edit" | "supersede" | "archive_old" | "reject";
+  warnings: string[];
+}
+
+export interface CandidateTrap {
+  id: string;
+  status: CandidateStatus;
+  quality_score: number;
+  quality: CandidateQuality;
+  trap: TrapInput;
+  evidence: TrapEvidenceInput[];
+  accepted_trap_id?: number;
+  accepted_scope?: Scope;
+  accepted_at?: string;
+  rejected_at?: string;
+  rejection_reason?: string;
+}
+
+export interface CandidateTrapDocument {
+  version: typeof SESSION_VERSION;
+  session_id: string;
+  candidates: CandidateTrap[];
+}
+
+export function parseSessionNoteKind(value: string | undefined): SessionNoteKind {
+  const normalized = value ?? "observation";
+  if ((SESSION_NOTE_KINDS as readonly string[]).includes(normalized)) {
+    return normalized as SessionNoteKind;
+  }
+  throw new Error(`Invalid session note kind: ${normalized}. Expected one of: ${SESSION_NOTE_KINDS.join(", ")}`);
+}

package/src/index.ts

@@ -14,6 +14,9 @@ if (args.length === 0) {
   showHelp();
 } else if (args[0] === "serve") {
   import("./mcp/server").then((m) => m.start());
+} else if (args[0] === "web") {
+  const { startWebServerFromArgs } = await import("./web/server");
+  await startWebServerFromArgs(args.slice(1));
 } else if (args[0] === "init") {
   const cwd = process.cwd();
   if (findProjectRoot(cwd)) {
@@ -43,6 +46,8 @@ function showHelp(): void {
   console.log("  archive_trap          Archive a trap");
   console.log("  supersede_trap        Mark one trap as superseded by another");
   console.log("  embed                 Generate embeddings for semantic search");
+  console.log("  session               Record implementation notes and capture candidate traps");
+  console.log("  web                   Start local review and trap library console");
   console.log("  export                Export traps as JSON");
   console.log("  import <file.json>    Import traps from JSON");
   console.log("  stats                 Show statistics");
@@ -63,6 +68,9 @@ function showHelp(): void {
   console.log("  --no-rerank             Disable query-aware search reranking");
   console.log("  --ranking-signals       Include search ranking diagnostics in JSON cards");
   console.log("  --batch-size <n>        Embedding generation batch size");
+  console.log("  --project <path>        Project path for web console");
+  console.log("  --host <host>           Host for web console (default 127.0.0.1)");
+  console.log("  --port <n>              Port for web console (default 4737)");
   console.log("  --json                  JSON output for search/show/list/stats/doctor; JSON input for add/edit");
   console.log("  --output-json           JSON output for add/edit when --json is used as input");
   console.log("  --from-project-path <path>  Source project path for scope repair/migration");

package/src/lib/command-requests.ts

@@ -16,6 +16,63 @@ export type StatsRequest = {
   scope?: string;
 };
 
+export type SessionStartRequest = {
+  goal: string;
+  specRef?: string;
+  module?: string;
+  owner?: string;
+};
+
+export type SessionNoteRequest = {
+  kind?: string;
+  text: string;
+  relatedFiles?: string[];
+  sourceRef?: string;
+};
+
+export type SessionListRequest = {
+  status?: string;
+  limit?: number;
+};
+
+export type SessionCloseRequest = {
+  sessionId?: string;
+  proposeTraps: boolean;
+};
+
+export type SessionIdRequest = {
+  sessionId?: string;
+};
+
+export type SessionShowRequest = {
+  sessionId: string;
+};
+
+export type SessionCandidateRequest = {
+  candidateId: string;
+  sessionId?: string;
+};
+
+export type SessionAcceptRequest = SessionCandidateRequest & {
+  edit?: Record<string, unknown>;
+  supersedesId?: number;
+  acceptAnyway: boolean;
+};
+
+export type SessionRejectRequest = SessionCandidateRequest & {
+  reason?: string;
+};
+
+export type SessionPruneRequest = {
+  olderThanDays: number;
+  apply: boolean;
+};
+
+export type SessionNoteStdin = {
+  isTTY: boolean;
+  read: () => string;
+};
+
 export function searchRequestFromArgs(query: string, args: RawArgs, defaults: SearchDefaults): SearchTrapsArgs {
   return {
     query,
@@ -70,6 +127,98 @@ export function evidenceRequestFromArgs(args: RawArgs): RawArgs {
   };
 }
 
+export function sessionStartRequestFromArgs(positionals: string[], args: RawArgs): SessionStartRequest {
+  const goal = positionals.join(" ").trim();
+  if (!goal) throw new Error("Session goal is required.");
+  return {
+    goal,
+    specRef: stringOption(args, "spec"),
+    module: stringOption(args, "module"),
+    owner: stringOption(args, "owner"),
+  };
+}
+
+export function sessionNoteRequestFromArgs(
+  positionals: string[],
+  args: RawArgs,
+  stdin: SessionNoteStdin
+): SessionNoteRequest {
+  const hasText = args.text !== undefined;
+  const hasStdin = args.stdin !== undefined;
+  if (hasText && hasStdin) throw new Error("Choose either --text or --stdin, not both.");
+  if (hasStdin && stdin.isTTY) throw new Error("--stdin requires piped input.");
+
+  const text = hasStdin
+    ? stdin.read().trim()
+    : stringOption(args, "text") ?? positionals.join(" ").trim();
+  if (!text) throw new Error("Session note text is required.");
+
+  return {
+    kind: stringOption(args, "kind"),
+    text,
+    relatedFiles: csvOrArrayOption(args, "related_files", "related-files"),
+    sourceRef: stringOption(args, "source_ref", "source-ref"),
+  };
+}
+
+export function sessionListRequestFromArgs(args: RawArgs): SessionListRequest {
+  return {
+    status: stringOption(args, "status") ?? "all",
+    limit: optionalIntOption(args, "limit"),
+  };
+}
+
+export function sessionCloseRequestFromArgs(positionals: string[], args: RawArgs): SessionCloseRequest {
+  return {
+    sessionId: positionals[0],
+    proposeTraps: flagPresent(args, "propose-traps"),
+  };
+}
+
+export function sessionIdRequestFromArgs(positionals: string[]): SessionIdRequest {
+  return {
+    sessionId: positionals[0],
+  };
+}
+
+export function sessionShowRequestFromArgs(positionals: string[]): SessionShowRequest {
+  return {
+    sessionId: requiredPositional(positionals, 0, "session-id"),
+  };
+}
+
+export function sessionCandidateRequestFromArgs(positionals: string[], args: RawArgs): SessionCandidateRequest {
+  return {
+    candidateId: requiredPositional(positionals, 0, "candidate-id"),
+    sessionId: stringOption(args, "session"),
+  };
+}
+
+export function sessionAcceptRequestFromArgs(positionals: string[], args: RawArgs): SessionAcceptRequest {
+  return {
+    ...sessionCandidateRequestFromArgs(positionals, args),
+    edit: jsonObjectOption(args, "edit-json"),
+    supersedesId: optionalIntOption(args, "supersedes"),
+    acceptAnyway: flagPresent(args, "accept-anyway"),
+  };
+}
+
+export function sessionRejectRequestFromArgs(positionals: string[], args: RawArgs): SessionRejectRequest {
+  return {
+    ...sessionCandidateRequestFromArgs(positionals, args),
+    reason: stringOption(args, "reason"),
+  };
+}
+
+export function sessionPruneRequestFromArgs(args: RawArgs): SessionPruneRequest {
+  const olderThan = stringOption(args, "older_than", "older-than");
+  if (!olderThan) throw new Error("--older-than is required.");
+  return {
+    olderThanDays: parseDurationDays(olderThan),
+    apply: flagPresent(args, "apply"),
+  };
+}
+
 function stringOption(args: RawArgs, ...keys: string[]): string | undefined {
   for (const key of keys) {
     const value = args[key];
@@ -131,3 +280,32 @@ function csvOrArrayOption(args: RawArgs, ...keys: string[]): string[] | undefine
   }
   return undefined;
 }
+
+function jsonObjectOption(args: RawArgs, key: string): Record<string, unknown> | undefined {
+  const value = stringOption(args, key);
+  if (value === undefined) return undefined;
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`${key} must be a JSON object.`);
+    }
+    return parsed as Record<string, unknown>;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid --${key}: ${message}`);
+  }
+}
+
+function parseDurationDays(value: string): number {
+  const match = value.trim().match(/^(\d+)\s*(d|day|days)?$/i);
+  if (!match) throw new Error(`Invalid duration: ${value}. Use a value like 90d.`);
+  const days = Number.parseInt(match[1], 10);
+  if (!Number.isInteger(days) || days <= 0) throw new Error(`Invalid duration: ${value}. Use a positive day count.`);
+  return days;
+}
+
+function requiredPositional(positionals: string[], index: number, name: string): string {
+  const value = positionals[index];
+  if (!value) throw new Error(`${name} is required.`);
+  return value;
+}

package/src/lib/doctor.ts

@@ -1,9 +1,14 @@
 import type { TrapStore } from "./store";
 import type { TrapOperations } from "./trap-operations";
-import type { EmbeddingStatsResult, HybridFallbackReason } from "./embedding-health";
+import type { EmbeddingStateSummary, EmbeddingStatsResult, HybridFallbackReason } from "./embedding-health";
 import { createScopeContext } from "./scope-context";
 import { hybridFallbackReason } from "./embedding-health";
 
+export type DoctorNextAction = {
+  command: string;
+  reason: string;
+};
+
 export type DoctorReport = {
   cwd: string;
   project_root: string | null;
@@ -23,6 +28,7 @@ export type DoctorReport = {
       global_db_project_traps: ReturnType<TrapStore["diagnostics"]>["mis_scoped_traps"]["global_db_project_traps"];
     };
   };
+  next_actions: DoctorNextAction[];
   mcp_hint: string;
 };
 
@@ -35,6 +41,7 @@ export function buildDoctorReport(
   const stats = operations.getStats();
   const embeddings = operations.getEmbeddingStats();
   const semanticAvailable = store.hasEmbeddingProvider();
+  const diagnostics = store.diagnostics();
 
   return {
     ...scope,
@@ -48,8 +55,9 @@ export function buildDoctorReport(
       fallback_reason: hybridFallbackReason(semanticAvailable, embeddings),
     },
     diagnostics: {
-      mis_scoped_traps: store.diagnostics().mis_scoped_traps,
+      mis_scoped_traps: diagnostics.mis_scoped_traps,
     },
+    next_actions: buildDoctorNextActions(semanticAvailable, embeddings, diagnostics),
     mcp_hint: "Pass cwd in MCP tool calls, or restart codetrap serve after changing projects.",
   };
 }
@@ -70,10 +78,62 @@ export function formatDoctorText(report: DoctorReport): string {
     `  fallback_reason: ${report.hybrid_search.fallback_reason ?? "(none)"}`,
     "Diagnostics:",
     `  global_db_project_traps: ${report.diagnostics.mis_scoped_traps.global_db_project_traps.length}`,
+    "Next actions:",
+    ...formatNextActions(report.next_actions),
     `mcp_hint: ${report.mcp_hint}`,
   ].join("\n");
 }
 
+function buildDoctorNextActions(
+  semanticAvailable: boolean,
+  embeddings: EmbeddingStatsResult,
+  diagnostics: ReturnType<TrapStore["diagnostics"]>
+): DoctorNextAction[] {
+  const actions: DoctorNextAction[] = [];
+  if (!semanticAvailable) {
+    actions.push({
+      command: "export JINA_API_KEY=<your-jina-api-key>",
+      reason: "Enable semantic and hybrid search; otherwise use --mode fts.",
+    });
+  } else {
+    const projectAction = embeddingRefreshAction("project", embeddings.project);
+    const globalAction = embeddingRefreshAction("global", embeddings.global);
+    if (projectAction) actions.push(projectAction);
+    if (globalAction) actions.push(globalAction);
+  }
+
+  const stranded = diagnostics.mis_scoped_traps.global_db_project_traps.length;
+  if (stranded > 0) {
+    actions.push({
+      command: "codetrap repair-scope --dry-run --json",
+      reason: `${stranded} project-scoped trap(s) are stored in the global database.`,
+    });
+  }
+  return actions;
+}
+
+function embeddingRefreshAction(
+  scope: "project" | "global",
+  stats: EmbeddingStateSummary | null
+): DoctorNextAction | null {
+  if (!stats || stats.total === 0) return null;
+  const needsRefresh = stats.missing + stats.stale;
+  if (needsRefresh === 0) return null;
+  const parts = [
+    stats.missing > 0 ? `${stats.missing} missing` : null,
+    stats.stale > 0 ? `${stats.stale} stale` : null,
+  ].filter((item): item is string => item !== null);
+  return {
+    command: `codetrap embed --scope ${scope}`,
+    reason: `${scope} embeddings need refresh (${parts.join(", ")}).`,
+  };
+}
+
+function formatNextActions(actions: DoctorNextAction[]): string[] {
+  if (actions.length === 0) return ["  (none)"];
+  return actions.map((action) => `  - ${action.command} # ${action.reason}`);
+}
+
 function formatEmbeddingStats(
   label: string,
   stats: EmbeddingStatsResult["global"] | null

package/src/lib/embed-output.ts

@@ -0,0 +1,26 @@
+export type EmbedCommandResult = {
+  generated: number;
+  skipped: number;
+  batches: number;
+  scopes: { scope: string; generated: number; skipped: number; batches: number }[];
+};
+
+export function formatEmbedText(result: EmbedCommandResult): string {
+  return [
+    ...result.scopes.map((scoped) =>
+      `[${scoped.scope}] embeddings generated: ${scoped.generated}, skipped: ${scoped.skipped}, batches: ${scoped.batches}`
+    ),
+    `Total generated: ${result.generated}, skipped: ${result.skipped}, batches: ${result.batches}`,
+    `Next: ${embedNextAction(result)}`,
+  ].join("\n");
+}
+
+function embedNextAction(result: EmbedCommandResult): string {
+  if (result.generated > 0) {
+    return 'codetrap search "<query>" --mode hybrid';
+  }
+  if (result.skipped > 0) {
+    return "embeddings are already fresh; run codetrap doctor to verify hybrid search.";
+  }
+  return "add traps first, then rerun codetrap embed --scope project or --scope global.";
+}

package/src/lib/scope-context.ts

@@ -15,14 +15,14 @@ export type ScopeContext = {
   global_db: string;
 };
 
-export function createScopeContext(cwd = process.cwd()): ScopeContext {
-  const resolvedCwd = resolveScopePath(cwd);
-  const projectRoot = findProjectRoot(resolvedCwd);
+export function createScopeContext(cwd = process.cwd(), home?: string): ScopeContext {
+  const resolvedCwd = resolveScopePath(cwd, home ?? cwd);
+  const projectRoot = findProjectRoot(resolvedCwd, home);
   return {
     cwd: resolvedCwd,
     project_root: projectRoot,
     project_db: projectRoot ? scopePath.join(projectRoot, CODETRAP_DIR, TRAPS_DB_FILE) : null,
-    global_db: getGlobalDB(),
+    global_db: getGlobalDB(home),
   };
 }
 
@@ -36,8 +36,8 @@ export class ScopedRepositoryContext {
   private globalRepository?: TrapRepository;
   private projectRepository?: TrapRepository;
 
-  constructor(cwd = process.cwd(), private readonly embedder?: EmbeddingProvider) {
-    this.context = createScopeContext(cwd);
+  constructor(cwd = process.cwd(), private readonly embedder?: EmbeddingProvider, private readonly home?: string) {
+    this.context = createScopeContext(cwd, home);
   }
 
   hasProject(): boolean {
@@ -94,7 +94,7 @@ export class ScopedRepositoryContext {
 
   private globalRepo(): TrapRepository {
     if (!this.globalRepository) {
-      this.globalRepository = new TrapRepository(openGlobal(), this.embedder);
+      this.globalRepository = new TrapRepository(openGlobal(this.home), this.embedder);
     }
     return this.globalRepository;
   }

package/src/lib/scope.ts

@@ -5,14 +5,14 @@ import { defaultScopePathResolver, resolveScopePath, ScopePathResolver } from ".
 
 export { resolveScopePath, ScopePathResolver } from "./scope-path";
 
-export function getGlobalDir(): string {
-  const dir = defaultScopePathResolver.join(homedir(), CODETRAP_DIR);
+export function getGlobalDir(homeDir = homedir()): string {
+  const dir = defaultScopePathResolver.join(homeDir, CODETRAP_DIR);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   return dir;
 }
 
-export function getGlobalDB(): string {
-  return defaultScopePathResolver.join(getGlobalDir(), TRAPS_DB_FILE);
+export function getGlobalDB(homeDir = homedir()): string {
+  return defaultScopePathResolver.join(getGlobalDir(homeDir), TRAPS_DB_FILE);
 }
 
 export function findProjectRoot(