codetrap 0.1.4 → 0.1.6

package/src/commands/workflow.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { TrapStore } from "../lib/store";
 import { formatTrapShort, formatTrapDetails, formatTrapActionCard } from "../lib/format";
 import type { Trap } from "../domain/trap";
+import type { SessionMetadata } from "../domain/session";
 import {
   formatScopeMigrationText,
   runScopeMigration,
@@ -10,6 +11,15 @@ import {
 import { TrapOperations } from "../lib/trap-operations";
 import { buildDoctorReport, formatDoctorText } from "../lib/doctor";
 import { searchDefaultsFromConfig } from "../lib/config";
+import { SessionStore } from "../lib/session-store";
+import { SessionOperations, type SessionConflictResult } from "../lib/session-operations";
+import {
+  CANDIDATES_FILE,
+  NOTES_FILE,
+  RECAP_FILE,
+  sessionRelativeDir,
+  sessionRelativeFile,
+} from "../lib/session-codec";
 import {
   toCliSearchJson,
   toListJson,
@@ -28,6 +38,15 @@ import {
   evidenceRequestFromArgs,
   listRequestFromArgs,
   searchRequestFromArgs,
+  sessionAcceptRequestFromArgs,
+  sessionCandidateRequestFromArgs,
+  sessionCloseRequestFromArgs,
+  sessionIdRequestFromArgs,
+  sessionListRequestFromArgs,
+  sessionNoteRequestFromArgs,
+  sessionRejectRequestFromArgs,
+  sessionShowRequestFromArgs,
+  sessionStartRequestFromArgs,
   statsRequestFromArgs,
 } from "../lib/command-requests";
 
@@ -80,10 +99,12 @@ export async function executeCommand(strip: string[], store: TrapStore): Promise
       return cmdScopeMigration("migrate-project", args, operations);
     case "embed":
       return cmdEmbed(args, store);
+    case "session":
+      return cmdSession(args, store, operations);
     default:
       return errorResult([
         `Unknown command: ${sub}`,
-        "Commands: init, add, search, list, show, edit, delete, add_trap_evidence, archive_trap, supersede_trap, export, import, stats, doctor, repair-scope, migrate-project, embed",
+        "Commands: init, add, search, list, show, edit, delete, add_trap_evidence, archive_trap, supersede_trap, export, import, stats, doctor, repair-scope, migrate-project, embed, session",
       ].join("\n"));
   }
 }
@@ -226,7 +247,7 @@ function cmdAddTrapEvidence(args: string[], operations: TrapOperations): Command
   const { opts, positionals } = parseArgs(args);
   const id = parseId(
     positionals[0],
-    "Usage: codetrap add_trap_evidence <id> --source_type manual|conversation|commit|issue|test_failure [--scope project|global] [--source_ref X] [--related_files a,b] [--note X]"
+    "Usage: codetrap add_trap_evidence <id> --source_type manual|conversation|commit|issue|test_failure|article [--scope project|global] [--source_ref X] [--related_files a,b] [--note X]"
   );
   if (typeof id !== "number") return id;
 
@@ -370,6 +391,204 @@ async function cmdEmbed(args: string[], store: TrapStore): Promise<CommandResult
   }
 }
 
+async function cmdSession(args: string[], store: TrapStore, trapOperations: TrapOperations): Promise<CommandResult> {
+  const sub = args[0];
+  const rest = args.slice(1);
+  const projectRoot = store.getProjectRoot();
+  if (!projectRoot) {
+    return errorResult("Not in a project. Run 'codetrap init' first.");
+  }
+
+  const sessions = new SessionOperations(new SessionStore(projectRoot), trapOperations);
+  try {
+    switch (sub) {
+      case "start":
+        return cmdSessionStart(rest, sessions);
+      case "note":
+        return cmdSessionNote(rest, sessions);
+      case "status":
+        return cmdSessionStatus(rest, sessions);
+      case "list":
+        return cmdSessionList(rest, sessions);
+      case "show":
+        return cmdSessionShow(rest, sessions);
+      case "notes":
+        return cmdSessionNotes(rest, sessions);
+      case "close":
+        return cmdSessionClose(rest, sessions);
+      case "candidates":
+        return cmdSessionCandidates(rest, sessions);
+      case "candidate":
+        return cmdSessionCandidate(rest, sessions);
+      case "accept":
+        return cmdSessionAccept(rest, sessions);
+      case "reject":
+        return cmdSessionReject(rest, sessions);
+      default:
+        return errorResult("Usage: codetrap session <start|note|status|list|show|notes|close|candidates|candidate|accept|reject>");
+    }
+  } catch (error) {
+    return errorFrom(error);
+  }
+}
+
+function cmdSessionStart(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const session = sessions.startSession(sessionStartRequestFromArgs(positionals, opts));
+  const payload = sessionPayload(session);
+  if (opts.json !== undefined) return jsonResult(payload);
+  return textResult([
+    `Started session ${session.id}`,
+    `Notes: ${payload.notes_path}`,
+  ].join("\n"));
+}
+
+function cmdSessionNote(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const result = sessions.addNote(sessionNoteRequestFromArgs(positionals, opts, {
+    isTTY: process.stdin.isTTY === true,
+    read: () => readFileSync(0, "utf-8"),
+  }));
+  const payload = {
+    session_id: result.session.id,
+    kind: result.note.kind,
+    note: result.note,
+    notes_path: result.notes_path,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  return textResult([
+    `Added ${result.note.kind} note to session ${result.session.id}.`,
+    `Notes: ${result.notes_path}`,
+  ].join("\n"));
+}
+
+function cmdSessionStatus(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts } = parseArgs(args);
+  const status = sessions.status();
+  if (opts.json !== undefined) {
+    return jsonResult({
+      active_session_id: status.active_session_id,
+      session: status.session ? sessionPayload(status.session) : null,
+    });
+  }
+  if (!status.session) return textResult("No active session.");
+  return textResult([
+    `Active session ${status.session.id}`,
+    `Goal: ${status.session.goal}`,
+    `Notes: ${sessionRelativeFile(status.session.id, NOTES_FILE)}`,
+  ].join("\n"));
+}
+
+function cmdSessionList(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts } = parseArgs(args);
+  const entries = sessions.listSessions(sessionListRequestFromArgs(opts));
+  if (opts.json !== undefined) return jsonResult(entries);
+  if (entries.length === 0) return textResult("No sessions found.");
+  return textResult(entries.map((entry) => `${entry.id} [${entry.status}] ${entry.goal}`).join("\n"));
+}
+
+function cmdSessionShow(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionShowRequestFromArgs(positionals);
+  const shown = sessions.showSession(request.sessionId);
+  if (opts.json !== undefined) {
+    return jsonResult({
+      ...sessionPayload(shown.session),
+      session_dir: shown.session_dir,
+      recap: shown.recap,
+    });
+  }
+  if (shown.recap) return textResult(shown.recap.trimEnd());
+  return textResult([
+    `Session ${shown.session.id} [${shown.session.status}]`,
+    `Goal: ${shown.session.goal}`,
+    `Notes: ${shown.notes_path}`,
+  ].join("\n"));
+}
+
+function cmdSessionNotes(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionIdRequestFromArgs(positionals);
+  const summary = sessions.summarizeNotes(request.sessionId);
+  if (opts.json !== undefined) return jsonResult(summary);
+  return textResult(summary.content.trimEnd());
+}
+
+function cmdSessionClose(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionCloseRequestFromArgs(positionals, opts);
+  const result = sessions.closeSession(request.sessionId, request.proposeTraps);
+  const payload = {
+    ...sessionPayload(result.session),
+    recap_path: result.recap_path,
+    candidate_count: result.candidate_count,
+    traps_written: result.traps_written,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  const lines = [
+    `Closed session ${result.session.id}`,
+    `Generated ${RECAP_FILE}`,
+  ];
+  if (opts["propose-traps"] !== undefined) {
+    lines.push(`Proposed ${result.candidate_count} candidate traps`);
+    lines.push(`0 traps were written. Use \`codetrap session accept <candidate-id> --session ${result.session.id}\` to save one.`);
+  }
+  return textResult(lines.join("\n"));
+}
+
+function cmdSessionCandidates(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionIdRequestFromArgs(positionals);
+  const document = sessions.candidateDocument(request.sessionId);
+  if (opts.json !== undefined) return jsonResult(document);
+  if (document.candidates.length === 0) return textResult("No candidate traps found.");
+  return textResult(document.candidates.map((candidate) =>
+    `${candidate.id} [${candidate.status}] ${candidate.trap.title} (${candidate.quality_score.toFixed(2)})`
+  ).join("\n"));
+}
+
+function cmdSessionCandidate(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const request = sessionCandidateRequestFromArgs(positionals, opts);
+  const result = sessions.getCandidate(request.candidateId, request.sessionId);
+  if (opts.json !== undefined) return jsonResult({ session_id: result.session.id, candidate: result.candidate });
+  return textResult(JSON.stringify(result.candidate, null, 2));
+}
+
+async function cmdSessionAccept(args: string[], sessions: SessionOperations): Promise<CommandResult> {
+  const { opts, positionals } = parseArgs(args);
+  const accepted = await sessions.acceptCandidate(sessionAcceptRequestFromArgs(positionals, opts));
+  if (!accepted.success) return possibleConflictResult(accepted, opts.json !== undefined);
+  const payload = {
+    success: true,
+    session_id: accepted.session.id,
+    candidate_id: accepted.candidate.id,
+    status: accepted.candidate.status,
+    trap_id: accepted.trap_id,
+    scope: accepted.scope,
+    evidence_id: accepted.evidence_id,
+    superseded_id: accepted.superseded_id,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  const lines = [`Accepted ${accepted.candidate.id}; wrote trap #${accepted.trap_id} to ${accepted.scope} scope.`];
+  if (accepted.superseded_id !== null) lines.push(`Superseded trap #${accepted.superseded_id}.`);
+  return textResult(lines.join("\n"));
+}
+
+function cmdSessionReject(args: string[], sessions: SessionOperations): CommandResult {
+  const { opts, positionals } = parseArgs(args);
+  const rejected = sessions.rejectCandidate(sessionRejectRequestFromArgs(positionals, opts));
+  const payload = {
+    success: true,
+    session_id: rejected.session.id,
+    candidate_id: rejected.candidate.id,
+    status: rejected.candidate.status,
+    reason: rejected.candidate.rejection_reason ?? null,
+  };
+  if (opts.json !== undefined) return jsonResult(payload);
+  return textResult(`Rejected ${rejected.candidate.id}.`);
+}
+
 function formatStatsText(stats: ReturnType<TrapOperations["getStats"]>): string {
   const sections: string[] = [];
   if (stats.project) {
@@ -417,3 +636,43 @@ function errorFrom(error: unknown): CommandResult {
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
+
+function sessionPayload(session: SessionMetadata) {
+  return {
+    ...session,
+    session_dir: sessionRelativeDir(session.id),
+    notes_path: sessionRelativeFile(session.id, NOTES_FILE),
+    recap_path: sessionRelativeFile(session.id, RECAP_FILE),
+    candidate_traps_path: sessionRelativeFile(session.id, CANDIDATES_FILE),
+  };
+}
+
+function possibleConflictResult(
+  result: SessionConflictResult,
+  asJson: boolean
+): CommandResult {
+  const payload = {
+    success: false,
+    error: "Possible active trap conflict found.",
+    session_id: result.session_id,
+    candidate_id: result.candidate_id,
+    possible_conflicts: result.possible_conflicts,
+    next_actions: [
+      `codetrap session accept ${result.candidate_id} --session ${result.session_id} --accept-anyway`,
+      `codetrap session accept ${result.candidate_id} --session ${result.session_id} --supersedes <trap-id>`,
+      `codetrap session reject ${result.candidate_id} --session ${result.session_id} --reason <reason>`,
+    ],
+  };
+  if (asJson) return jsonResult(payload, 1);
+
+  return errorResult([
+    "Possible active trap conflict found:",
+    ...result.possible_conflicts.map((conflict) => [
+      `#${conflict.trap_id} ${conflict.title}`,
+      `  reason: ${conflict.reason}`,
+      `  fix: ${conflict.fix}`,
+    ].join("\n")),
+    "",
+    `Use --accept-anyway to save as a new trap, or --supersedes <trap-id> to preserve lifecycle history.`,
+  ].join("\n"));
+}

package/src/db/connection.ts

@@ -29,8 +29,8 @@ export function openProject(root: string): Database {
 }
 
 function configureDatabase(db: Database): void {
+  db.exec("PRAGMA busy_timeout=5000");
   db.exec("PRAGMA journal_mode=WAL");
   db.exec("PRAGMA foreign_keys=ON");
-  db.exec("PRAGMA busy_timeout=5000");
   initSchema(db);
 }

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/domain/trap.ts

@@ -246,7 +246,7 @@ export function trapEvidenceInputSchema(): JsonSchema {
         enum: [...EVIDENCE_SOURCE_TYPES] as string[],
         description: "Where this evidence came from",
       },
-      source_ref: { type: "string", description: "Optional file path, commit SHA, issue URL, or transcript ID" },
+      source_ref: { type: "string", description: "Optional file path, commit SHA, issue/article URL, or transcript ID" },
       observed_at: { type: "string", description: "When this was observed (ISO-like timestamp, optional)" },
       related_files: {
         type: "array",

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 candidate review console");
   console.log("  export                Export traps as JSON");
   console.log("  import <file.json>    Import traps from JSON");
   console.log("  stats                 Show statistics");
@@ -59,9 +64,13 @@ function showHelp(): void {
   console.log("  --path <file>           Filter/boost traps scoped to a file path");
   console.log("  --module <name>         Filter/boost traps scoped to a module");
   console.log("  --owner <name>          Filter/boost traps scoped to an owner/team");
+  console.log("  --source_type <type>    Evidence source: manual, conversation, commit, issue, test_failure, article");
   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 review console");
+  console.log("  --host <host>           Host for web review console (default 127.0.0.1)");
+  console.log("  --port <n>              Port for web review 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,58 @@ 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 SessionNoteStdin = {
+  isTTY: boolean;
+  read: () => string;
+};
+
 export function searchRequestFromArgs(query: string, args: RawArgs, defaults: SearchDefaults): SearchTrapsArgs {
   return {
     query,
@@ -70,6 +122,89 @@ 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"),
+  };
+}
+
 function stringOption(args: RawArgs, ...keys: string[]): string | undefined {
   for (const key of keys) {
     const value = args[key];
@@ -131,3 +266,24 @@ 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 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/constants.ts

@@ -37,7 +37,7 @@ export type Scope = (typeof SCOPES)[number];
 export const TRAP_STATUSES = ["active", "superseded", "archived"] as const;
 export type TrapStatus = (typeof TRAP_STATUSES)[number];
 
-export const EVIDENCE_SOURCE_TYPES = ["manual", "conversation", "commit", "issue", "test_failure"] as const;
+export const EVIDENCE_SOURCE_TYPES = ["manual", "conversation", "commit", "issue", "test_failure", "article"] as const;
 export type EvidenceSourceType = (typeof EVIDENCE_SOURCE_TYPES)[number];
 
 export const SEARCH_MODES = ["fts", "semantic", "hybrid"] as const;