@chude/memory 4.0.0

package/dist/presentation/cli/commands/uninstall.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Uninstall Command Handler
+ *
+ * CLI command for removing Claude Code hooks.
+ * Removes hook entries from settings.json and deletes hook script.
+ */
+import { Command } from "commander";
+import type { CommandResult } from "../command-result.js";
+/**
+ * Options for the uninstall command.
+ */
+export interface UninstallOptions {
+    /** Restore settings.json from backup instead of removing hooks */
+    restore?: boolean;
+}
+/**
+ * Runtime dependencies for executeUninstallCommand.
+ *
+ * Operational dependencies that tests substitute for isolation.
+ * Defaults to production resolution when omitted.
+ */
+export interface UninstallCommandDeps {
+    /**
+     * Override settings/backup/hook-script paths used by settings-manager.
+     */
+    hookOverrides?: import("../../../infrastructure/hooks/settings-manager.js").PathOverrides;
+}
+/**
+ * Create the uninstall command for Commander.js.
+ *
+ * @returns Configured Command instance
+ */
+export declare function createUninstallCommand(): Command;
+/**
+ * Execute the uninstall command programmatically.
+ *
+ * Removes Claude Code hooks installed by the install command. Deletes
+ * hook entries from settings.json and removes the hook script file.
+ * Returns exitCode 0 if hooks are not installed (idempotent).
+ *
+ * @param options - Uninstall command options
+ * @returns CommandResult with exitCode 0 (success/not installed)
+ */
+export declare function executeUninstallCommand(options: UninstallOptions, deps?: UninstallCommandDeps): Promise<CommandResult>;

package/dist/presentation/cli/db-startup.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Database Startup Utilities
+ *
+ * Handles database initialization with integrity checks and recovery options.
+ * Provides user-friendly prompts for corrupted database scenarios.
+ */
+import { type DatabaseConfig, type DatabaseInitResult } from "../../infrastructure/database/index.js";
+import { MemoryError } from "../../domain/index.js";
+interface TtyLikeStream {
+    isTTY?: boolean | undefined;
+}
+/**
+ * Options for database startup.
+ */
+export interface DbStartupOptions {
+    /** JSON output mode */
+    json?: boolean;
+    /** Verbose mode for error details */
+    verbose?: boolean;
+    /** Custom database path (defaults to getDefaultDbPath()) */
+    dbPath?: string;
+    /** Skip integrity check on startup */
+    skipCheck?: boolean;
+}
+/**
+ * Result of database startup.
+ */
+export type DbStartupResult = {
+    success: true;
+    db: DatabaseInitResult["db"];
+} | {
+    success: false;
+    error: MemoryError;
+};
+export interface DbStartupDeps {
+    existsSync?: (path: string) => boolean;
+    getDefaultDbPath?: () => string;
+    initializeDatabaseSafe?: (config: DatabaseConfig) => DatabaseInitResult;
+    isTTY?: () => boolean;
+    confirm?: (message: string) => Promise<boolean>;
+    backupCorruptedDatabase?: (dbPath: string) => string;
+}
+/**
+ * Check if running in an interactive TTY environment.
+ *
+ * @returns true if stdin and stdout are TTYs
+ */
+export declare function isTTY(input?: TtyLikeStream, output?: TtyLikeStream): boolean;
+/**
+ * Initialize database with startup checks and error handling.
+ *
+ * Performs:
+ * 1. Quick integrity check (for existing databases)
+ * 2. Error handling with user-friendly messages
+ * 3. Recovery prompt for corrupted databases (in TTY)
+ *
+ * @param options Startup options
+ * @returns Database startup result
+ */
+export declare function initializeDatabaseForCli(options?: DbStartupOptions, deps?: DbStartupDeps): Promise<DbStartupResult>;
+export {};

package/dist/presentation/cli/formatters/ai-formatter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * AI Formatter Utility
+ *
+ * Shared utility for producing clean, token-efficient text output.
+ * Used by --format ai across all commands and by the smart context
+ * service for budget estimation.
+ */
+/**
+ * Strip all ANSI escape sequences from text.
+ *
+ * Removes SGR (color/style), CSI (cursor/screen), OSC (title),
+ * and charset selection sequences.
+ *
+ * @param text Input text potentially containing ANSI codes
+ * @returns Plain text with all escape sequences removed
+ */
+export declare function stripAnsi(text: string): string;
+/**
+ * Estimate token count using a chars-per-token heuristic.
+ *
+ * Default ratio of 4 characters per token approximates GPT/Claude
+ * tokenization for English text.
+ *
+ * @param text Input text to estimate
+ * @param charsPerToken Characters per token (default: 4)
+ * @returns Estimated token count (ceiling)
+ */
+export declare function estimateTokens(text: string, charsPerToken?: number): number;
+/**
+ * Format text for AI consumption.
+ *
+ * Strips ANSI codes, collapses multiple blank lines to a single
+ * blank line, and trims leading/trailing whitespace.
+ *
+ * @param text Input text with potential ANSI codes and irregular whitespace
+ * @returns Clean, normalized text suitable for AI processing
+ */
+export declare function formatForAi(text: string): string;

package/dist/presentation/cli/formatters/color.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Color Utilities
+ *
+ * TTY-aware color output for CLI commands.
+ * Respects NO_COLOR and FORCE_COLOR environment variables.
+ */
+/**
+ * Options for color detection.
+ */
+export interface ColorOptions {
+    isTTY?: boolean;
+    noColor?: boolean;
+    forceColor?: boolean;
+}
+/**
+ * Determine if color output should be used.
+ *
+ * Priority order:
+ * 1. NO_COLOR env var or noColor option (disables color)
+ * 2. FORCE_COLOR env var or forceColor option (enables color)
+ * 3. TTY detection (enables color if TTY)
+ *
+ * @param options Color detection options
+ * @returns True if color should be used
+ */
+export declare function shouldUseColor(options?: ColorOptions): boolean;
+/**
+ * Make text bold.
+ *
+ * @param text Text to make bold
+ * @param useColor Whether to apply color (defaults to shouldUseColor())
+ * @returns Bold text or plain text
+ */
+export declare function bold(text: string, useColor?: boolean): string;
+/**
+ * Make text dim.
+ *
+ * @param text Text to make dim
+ * @param useColor Whether to apply color (defaults to shouldUseColor())
+ * @returns Dim text or plain text
+ */
+export declare function dim(text: string, useColor?: boolean): string;
+/**
+ * Make text green.
+ *
+ * @param text Text to make green
+ * @param useColor Whether to apply color (defaults to shouldUseColor())
+ * @returns Green text or plain text
+ */
+export declare function green(text: string, useColor?: boolean): string;
+/**
+ * Make text red.
+ *
+ * @param text Text to make red
+ * @param useColor Whether to apply color (defaults to shouldUseColor())
+ * @returns Red text or plain text
+ */
+export declare function red(text: string, useColor?: boolean): string;
+/**
+ * Make text yellow.
+ *
+ * @param text Text to make yellow
+ * @param useColor Whether to apply color (defaults to shouldUseColor())
+ * @returns Yellow text or plain text
+ */
+export declare function yellow(text: string, useColor?: boolean): string;
+/**
+ * Make text cyan (for highlighting matches).
+ *
+ * @param text Text to make cyan
+ * @param useColor Whether to apply color (defaults to shouldUseColor())
+ * @returns Cyan text or plain text
+ */
+export declare function cyan(text: string, useColor?: boolean): string;
+/**
+ * Make text bold and cyan (for highly visible highlighting).
+ *
+ * @param text Text to make bold and cyan
+ * @param useColor Whether to apply color (defaults to shouldUseColor())
+ * @returns Bold cyan text or plain text
+ */
+export declare function boldCyan(text: string, useColor?: boolean): string;

package/dist/presentation/cli/formatters/context-formatter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Context Formatter
+ *
+ * Strategy pattern for formatting project context output.
+ * Supports brief, detailed, JSON, quiet, and verbose output modes.
+ */
+import type { ProjectContext } from "../../../infrastructure/database/services/context-service.js";
+import type { SmartContextResult } from "../../../application/services/smart-context-service.js";
+/**
+ * Output mode for context formatter.
+ */
+export type ContextOutputMode = "default" | "json" | "brief" | "detailed" | "quiet" | "verbose" | "ai";
+/**
+ * Options for formatting context.
+ */
+export interface ContextFormatOptions {
+    /** Execution time in milliseconds */
+    executionTimeMs?: number;
+    /** List of filters that were applied */
+    filtersApplied?: string[];
+}
+/**
+ * Context formatter interface.
+ */
+export interface ContextFormatter {
+    /**
+     * Format project context for display.
+     */
+    formatContext(context: ProjectContext, options?: ContextFormatOptions): string;
+    /**
+     * Format smart context result with structured sections.
+     * Only implemented by AI formatter; other formatters may leave undefined.
+     */
+    formatSmartContext?(result: SmartContextResult): string;
+    /**
+     * Format an error message.
+     */
+    formatError(error: Error): string;
+    /**
+     * Format empty result message (project not found).
+     */
+    formatEmpty(projectName: string): string;
+    /**
+     * Format message when no topics extracted yet.
+     */
+    formatNoTopics(): string;
+}
+/**
+ * Create a context formatter for the given mode.
+ *
+ * @param mode Output mode
+ * @param useColor Whether to use ANSI colors
+ * @returns ContextFormatter instance
+ */
+export declare function createContextFormatter(mode: ContextOutputMode, useColor: boolean): ContextFormatter;

package/dist/presentation/cli/formatters/dto-helpers.d.ts

@@ -0,0 +1,176 @@
+/**
+ * DTO helpers for query command JSON output.
+ *
+ * Extracted from JsonOutputFormatter (per Codex MEDIUM-1) so each command
+ * can build its envelope `data` field using a pure, testable transformation.
+ *
+ * INVARIANT (Gemini LOW): highlight offsets MUST be computed BEFORE
+ * <mark> tags are stripped. Computing after-strip would always produce
+ * offset 0 (no tags remain). See toSearchResultDto.
+ *
+ * CONTEXT_BUDGET BOUNDARY (Codex MEDIUM-1): the iterative truncation loop
+ * that fits results within the 50K-char budget lives in
+ * JsonOutputFormatter (output-formatter.ts), NOT here. DTO helpers
+ * transform shape; the formatter owns truncation. Plan 32-02's envelope
+ * path skips truncation because envelope consumers expect a stable
+ * data array, not a heuristically-trimmed prefix.
+ */
+import type { SearchResult } from "../../../domain/value-objects/search-result.js";
+import type { Session } from "../../../domain/entities/session.js";
+import type { QmdSearchResult } from "../../../domain/ports/services.js";
+import type { ProjectContext } from "../../../infrastructure/database/services/context-service.js";
+import type { ExtendedStatsResult } from "./stats-formatter.js";
+import type { SessionDetail } from "./show-formatter.js";
+import type { RelatedSession } from "./related-formatter.js";
+/**
+ * DTO for a single search result in JSON output.
+ *
+ * Mirrors the legacy JsonOutputFormatter.formatResults() shape so
+ * existing consumers see the same fields wrapped in the envelope's
+ * `data` array.
+ */
+export interface SearchResultDto {
+    sessionId: string;
+    messageId: string;
+    role: string;
+    score: number;
+    timestamp: string;
+    snippet: string;
+    rank?: number;
+    raw_scores?: {
+        bm25?: number | undefined;
+        cosine?: number | undefined;
+        rrf?: number | undefined;
+    } | undefined;
+    source?: "fts" | "vector" | "both";
+    highlights?: Array<{
+        offset: number;
+        length: number;
+    }>;
+}
+/**
+ * Convert a SearchResult value-object into a JSON-emitting DTO.
+ *
+ * - highlights are computed from the ORIGINAL snippet before <mark>
+ *   stripping (Gemini LOW invariant).
+ * - hybrid-search-meta fields (rank, raw_scores, source, highlights)
+ *   are only included when includeSearchMetaFields is true — preserving
+ *   the legacy behavior where these were gated on options.searchMeta.
+ */
+export declare function toSearchResultDto(result: SearchResult, opts?: {
+    rank?: number;
+    includeSearchMetaFields?: boolean;
+}): SearchResultDto;
+/**
+ * DTO for a single qmd file-search result.
+ *
+ * Mirrors the QmdSearchResult shape so consumers see the same fields
+ * wrapped in the envelope (instead of the bespoke bare array that
+ * leaked in the pre-Plan-32-02 code).
+ */
+export interface FileResultDto {
+    docid?: string;
+    score: number;
+    file: string;
+    title: string;
+    context?: string;
+    snippet?: string;
+}
+export declare function toFileResultDto(result: QmdSearchResult): FileResultDto;
+/**
+ * DTO for a session entry in the `list` command output.
+ *
+ * Mirrors the existing list-formatter JSON shape.
+ */
+export interface SessionListDto {
+    id: string;
+    project: string;
+    projectPath: string;
+    startTime: string;
+    endTime?: string;
+    messageCount?: number;
+    summary?: string;
+}
+export declare function toSessionListDto(session: Session): SessionListDto;
+/**
+ * DTO for a message in the `show` command output.
+ */
+export interface ShowMessageDto {
+    id: string;
+    role: string;
+    timestamp: string;
+    content: string;
+    toolUseIds?: string[];
+}
+/**
+ * DTO for a tool use in the `show` command output.
+ */
+export interface ShowToolUseDto {
+    id: string;
+    name: string;
+    status: string;
+    input: Record<string, unknown>;
+    result?: string;
+}
+/**
+ * DTO for `show` command — session + messages + tool uses.
+ */
+export interface ShowSessionDto {
+    session: SessionListDto;
+    messages: ShowMessageDto[];
+    toolUses: ShowToolUseDto[];
+}
+export declare function toShowSessionDto(detail: SessionDetail): ShowSessionDto;
+/**
+ * DTO for a related-session entry in the `related` command output.
+ */
+export interface RelatedDto {
+    session: SessionListDto;
+    weight: number;
+    hops: number;
+}
+export declare function toRelatedDto(item: RelatedSession): RelatedDto;
+/**
+ * DTO for the `stats` command output.
+ *
+ * Mirrors ExtendedStatsResult shape: totals plus per-project breakdown
+ * and optional hooks summary.
+ */
+export interface StatsDto {
+    totalSessions: number;
+    totalMessages: number;
+    totalToolUses: number;
+    databaseSizeBytes: number;
+    projectBreakdown: Array<{
+        projectName: string;
+        sessionCount: number;
+        messageCount: number;
+    }>;
+    hooks?: {
+        installed: boolean;
+        autoSync: boolean;
+        pendingSessions: number;
+    };
+}
+export declare function toStatsDto(stats: ExtendedStatsResult): StatsDto;
+/**
+ * DTO for the `context` command output.
+ *
+ * Mirrors ProjectContext shape so envelope `data` carries the same
+ * information the legacy formatter renders.
+ */
+export interface ContextDto {
+    projectName: string;
+    projectPathDecoded: string;
+    sessionCount: number;
+    totalMessages: number;
+    userMessages: number;
+    assistantMessages: number;
+    recentTopics: string[];
+    recentToolUses: Array<{
+        name: string;
+        count: number;
+    }>;
+    lastActivity: string | null;
+}
+export declare function toContextDto(context: ProjectContext): ContextDto;

package/dist/presentation/cli/formatters/envelope.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Uniform JSON envelope for query commands (CLI-02 foundation).
+ *
+ * SCHEMA VERSION POLICY:
+ * Bump ENVELOPE_SCHEMA_VERSION ONLY when the field set changes in a
+ * backward-incompatible way:
+ *   - Renaming a top-level field (e.g., `data` → `payload`)
+ *   - Changing a field type (e.g., `kind: string` → `kind: object`)
+ *   - Removing a field
+ *   - Changing semantics of an existing field
+ *
+ * Additive changes (new optional fields, new kinds in QUERY_RESULT_KINDS,
+ * new entries in EnvelopeScope union) do NOT bump the schema version.
+ * Consumers should ignore unknown fields gracefully.
+ *
+ * Phase 32.5 forward-compat: `kind` and `scope` are reserved for the
+ * unified query primitive (`memory query --scope <project|global>
+ * --kind <message|session|...>`). Phase 32 sets `kind` from the command
+ * name; Phase 32.5 will set `kind` from a CLI flag. No schema change.
+ */
+/**
+ * Current envelope schema version. Bump only per the policy above.
+ */
+export declare const ENVELOPE_SCHEMA_VERSION: "1";
+/**
+ * Runtime tuple of query command names. Types derived from this so callers
+ * can use both the values (e.g. `QUERY_COMMAND_NAMES.includes(x)`) and the
+ * literal union type (`QueryCommandName`). Per Codex HIGH-1.
+ */
+export declare const QUERY_COMMAND_NAMES: readonly ["search", "context", "show", "list", "related", "stats", "query"];
+/**
+ * Union of valid query command names, derived from QUERY_COMMAND_NAMES.
+ */
+export type QueryCommandName = (typeof QUERY_COMMAND_NAMES)[number];
+/**
+ * Runtime tuple of result kinds. Includes `"file"` so `search --files`
+ * (HIGH-4) has a stable kind in the envelope. Phase 32.5 will route the
+ * unified query primitive's `--kind` flag through this same set.
+ */
+export declare const QUERY_RESULT_KINDS: readonly ["message", "session", "context", "related", "stats", "file"];
+/**
+ * Union of valid query result kinds, derived from QUERY_RESULT_KINDS.
+ */
+export type QueryResultKind = (typeof QUERY_RESULT_KINDS)[number];
+/**
+ * Discriminated union for envelope scope. Maps 1:1 to Phase 32.5's
+ * `--scope global|project [--project <name>]` without ambiguity.
+ * Per Codex MEDIUM-4.
+ */
+export type EnvelopeScope = {
+    type: "global";
+} | {
+    type: "project";
+    project: string;
+};
+/**
+ * Success envelope shape. `data` is generic so each command can carry
+ * its own payload type. `schema_version` is a literal "1" so consumers
+ * can branch on shape evolution.
+ */
+export interface QueryResultEnvelope<T = unknown> {
+    schema_version: typeof ENVELOPE_SCHEMA_VERSION;
+    command: QueryCommandName;
+    kind: QueryResultKind;
+    scope?: EnvelopeScope;
+    meta?: Record<string, unknown>;
+    data: T;
+}
+/**
+ * Error envelope shape. `error.code` is a domain ErrorCode string
+ * (e.g. "DB_CONNECTION_FAILED"); `error.context` carries structured
+ * details from MemoryError instances.
+ */
+export interface QueryErrorEnvelope {
+    schema_version: typeof ENVELOPE_SCHEMA_VERSION;
+    command: QueryCommandName;
+    error: {
+        code: string;
+        message: string;
+        context?: Record<string, unknown>;
+    };
+}
+/**
+ * Construct a success envelope. Optional fields are omitted from the
+ * resulting object when undefined (no `"scope": undefined` leakage in
+ * JSON.stringify output).
+ */
+export declare function buildEnvelope<T>(args: {
+    command: QueryCommandName;
+    kind: QueryResultKind;
+    data: T;
+    scope?: EnvelopeScope;
+    meta?: Record<string, unknown>;
+}): QueryResultEnvelope<T>;
+/**
+ * Construct an error envelope. `error.context` is omitted when undefined.
+ */
+export declare function buildErrorEnvelope(args: {
+    command: QueryCommandName;
+    code: string;
+    message: string;
+    context?: Record<string, unknown>;
+}): QueryErrorEnvelope;
+/**
+ * Emit a success envelope to stdout as pretty-printed JSON.
+ *
+ * Per Codex HIGH-2: this is the canonical write surface for Plan 02
+ * success/empty-result branches. Every query command's exit path routes
+ * through here so stdout shape stays uniform.
+ *
+ * Does NOT set process.exitCode — the caller still returns
+ * `{ exitCode: 0 }` (or whatever CommandResult shape it uses).
+ */
+export declare function emitJsonEnvelope<T>(args: {
+    command: QueryCommandName;
+    kind: QueryResultKind;
+    data: T;
+    scope?: EnvelopeScope;
+    meta?: Record<string, unknown>;
+}): void;
+/**
+ * Emit an error envelope to stdout as pretty-printed JSON.
+ *
+ * Per Codex HIGH-2: this is the canonical write surface for Plan 02
+ * validation/not-found/catch branches. Every error exit path routes
+ * through here so stdout shape stays uniform regardless of failure mode.
+ *
+ * Does NOT set process.exitCode — the caller still returns
+ * `{ exitCode: 1 }` (or whatever CommandResult shape it uses).
+ */
+export declare function emitJsonErrorEnvelope(args: {
+    command: QueryCommandName;
+    code: string;
+    message: string;
+    context?: Record<string, unknown>;
+}): void;

package/dist/presentation/cli/formatters/error-formatter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Error Formatter
+ *
+ * Formats errors for CLI output with context, suggestions, and color.
+ */
+import { MemoryError, type ErrorCodeType } from "../../../domain/index.js";
+/**
+ * Options for error formatting.
+ */
+export interface ErrorFormatOptions {
+    /**
+     * Include stack trace in output.
+     */
+    verbose?: boolean;
+    /**
+     * Override TTY detection for color.
+     */
+    useColor?: boolean;
+}
+/**
+ * Get a suggestion for corrective action based on error code.
+ *
+ * @param code Error code
+ * @returns Suggestion string or null if no suggestion available
+ */
+export declare function getSuggestion(code: ErrorCodeType): string | null;
+/**
+ * Format an error for human-readable CLI output.
+ *
+ * @param error Error to format
+ * @param options Formatting options
+ * @returns Formatted error string
+ */
+export declare function formatError(error: Error | MemoryError, options?: ErrorFormatOptions): string;
+/**
+ * Format an error as JSON for programmatic consumption.
+ *
+ * @param error Error to format
+ * @returns JSON string with structured error
+ */
+export declare function formatErrorJson(error: Error | MemoryError): string;

package/dist/presentation/cli/formatters/friction-dashboard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Friction Dashboard Formatters
+ *
+ * Two formatters for friction data visualization:
+ * 1. formatFrictionDashboard - Rich terminal output with ASCII bars
+ * 2. generateFrictionHtml - Self-contained HTML with Chart.js charts
+ *
+ * Uses color.ts utilities for terminal coloring and reads Chart.js UMD
+ * source from node_modules at HTML generation time (no CDN dependency).
+ */
+import type { FrictionStats, FrictionPattern } from "../../../domain/ports/repositories.js";
+import type { FrictionEntry } from "../../../domain/entities/friction-entry.js";
+/**
+ * Render a rich terminal dashboard for friction stats.
+ *
+ * Displays overview counts, severity/category breakdowns with ASCII
+ * bar charts, MTTR, oldest open entry, and weekly trends table.
+ *
+ * @param stats Aggregated friction statistics
+ * @param trends Weekly new/resolved counts
+ * @param openItems Currently open friction entries
+ * @param useColor Whether to apply ANSI color codes
+ * @returns Formatted dashboard string
+ */
+export declare function formatFrictionDashboard(stats: FrictionStats, trends: Array<{
+    week: string;
+    newCount: number;
+    resolvedCount: number;
+}>, _openItems: FrictionEntry[], useColor: boolean, patterns?: FrictionPattern[]): string;
+/**
+ * Generate a self-contained HTML friction dashboard.
+ *
+ * The HTML file embeds Chart.js inline (no CDN), uses a dark theme,
+ * and includes 4 chart types: line (over time), doughnut (by category),
+ * horizontal bar (by severity), and grouped bar (resolution trend).
+ *
+ * @param stats Aggregated friction statistics
+ * @param trends Weekly new/resolved counts
+ * @param openItems Currently open friction entries
+ * @returns Complete HTML document string
+ */
+export declare function generateFrictionHtml(stats: FrictionStats, trends: Array<{
+    week: string;
+    newCount: number;
+    resolvedCount: number;
+}>, openItems: FrictionEntry[], patterns?: FrictionPattern[]): string;