squish-memory 1.0.2 → 1.1.5

package/dist/core/lib/db-client.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Database Client & Schema Loading Abstraction
+ *
+ * Provides a unified interface for accessing both the database client and schema
+ * in a single call, eliminating repetitive patterns of:
+ *   `const db = createDatabaseClient(await getDb()); const schema = await getSchema();`
+ *
+ * Features:
+ * - Single async call to get both db and schema
+ * - Consistent error handling with clear messages
+ * - Preserves schema caching
+ * - Provides raw connection for special cases
+ * - Helper `withDbClient` for functional programming patterns
+ *
+ * @example
+ * ```typescript
+ * // Old pattern (repetitive)
+ * const db = createDatabaseClient(await getDb());
+ * const schema = await getSchema();
+ *
+ * // New pattern (unified)
+ * const { db, schema } = await getDbClient();
+ *
+ * // With helper
+ * const result = await withDbClient(async (client) => {
+ *   return await client.db.select().from(client.schema.memories);
+ * });
+ * ```
+ */
+import type { DatabaseClient } from '../storage/database.js';
+import type { SchemaModule } from '../../db/schema.js';
+/**
+ * Unified database client interface combining:
+ * - `db`: Wrapped database client with select/insert/update/delete methods
+ * - `schema`: Drizzle schema module with table definitions
+ * - `raw`: Raw underlying connection for special cases (mcp-server, index, etc.)
+ */
+export interface DbClient {
+    /**
+     * Wrapped database client with unified API
+     * Provides select(), insert(), update(), delete() methods
+     */
+    db: DatabaseClient;
+    /**
+     * Schema module containing table definitions
+     * Access tables via schema.tableName (e.g., schema.memories, schema.users)
+     */
+    schema: SchemaModule;
+    /**
+     * Raw underlying database connection
+     * Use for special cases that require direct access to the native driver
+     * (e.g., raw SQL queries, specific driver features)
+     */
+    raw: any;
+}
+/**
+ * Get a unified database client with both db and schema.
+ *
+ * This function:
+ * 1. Calls getDb() to initialize/retrieve the database connection
+ * 2. Calls getSchema() to get the appropriate schema (with caching)
+ * 3. Wraps the db with createDatabaseClient() for unified API
+ * 4. Returns all three as a single DbClient object
+ *
+ * Error handling:
+ * - Wraps any database initialization errors with a clear message
+ * - Preserves the original error as `cause` property
+ *
+ * Schema caching:
+ * - Uses the same caching mechanism as getSchema()
+ * - Multiple calls to getDbClient() will return the same schema reference
+ *
+ * @returns Promise<DbClient> Unified client with db, schema, and raw
+ * @throws {Error} When database initialization fails, with cause attached
+ *
+ * @example
+ * ```typescript
+ * const { db, schema, raw } = await getDbClient();
+ *
+ * // Use db for queries
+ * const memories = await db.select().from(schema.memories).limit(10);
+ *
+ * // Use raw for special cases
+ * const client = (raw as any).$client;
+ * if (client && typeof client.exec === 'function') {
+ *   client.exec('VACUUM');
+ * }
+ * ```
+ */
+export declare function getDbClient(): Promise<DbClient>;
+/**
+ * Execute an operation with a unified database client.
+ *
+ * Convenience wrapper that:
+ * 1. Calls getDbClient() to obtain client
+ * 2. Executes the provided operation
+ * 3. Ensures proper cleanup if needed (no-op currently, for future extension)
+ *
+ * @param operation - Async function that receives the DbClient and returns a result
+ * @returns Promise<T> The result returned by the operation
+ * @throws {Error} When database initialization or operation fails
+ *
+ * @example
+ * ```typescript
+ * const count = await withDbClient(async (client) => {
+ *   const result = await client.db
+ *     .select({ count: sql`count(*)` })
+ *     .from(client.schema.memories);
+ *   return result[0].count;
+ * });
+ * ```
+ */
+export declare function withDbClient<T>(operation: (client: DbClient) => Promise<T>): Promise<T>;
+//# sourceMappingURL=db-client.d.ts.map

package/dist/core/lib/db-client.js

@@ -0,0 +1,130 @@
+/**
+ * Database Client & Schema Loading Abstraction
+ *
+ * Provides a unified interface for accessing both the database client and schema
+ * in a single call, eliminating repetitive patterns of:
+ *   `const db = createDatabaseClient(await getDb()); const schema = await getSchema();`
+ *
+ * Features:
+ * - Single async call to get both db and schema
+ * - Consistent error handling with clear messages
+ * - Preserves schema caching
+ * - Provides raw connection for special cases
+ * - Helper `withDbClient` for functional programming patterns
+ *
+ * @example
+ * ```typescript
+ * // Old pattern (repetitive)
+ * const db = createDatabaseClient(await getDb());
+ * const schema = await getSchema();
+ *
+ * // New pattern (unified)
+ * const { db, schema } = await getDbClient();
+ *
+ * // With helper
+ * const result = await withDbClient(async (client) => {
+ *   return await client.db.select().from(client.schema.memories);
+ * });
+ * ```
+ */
+import { getDb } from '../../db/index.js';
+import { getSchema } from '../../db/schema.js';
+import { createDatabaseClient } from '../storage/database.js';
+/**
+ * Internal cached schema to preserve getSchema() caching behavior
+ */
+let cachedSchema = null;
+/**
+ * Get a unified database client with both db and schema.
+ *
+ * This function:
+ * 1. Calls getDb() to initialize/retrieve the database connection
+ * 2. Calls getSchema() to get the appropriate schema (with caching)
+ * 3. Wraps the db with createDatabaseClient() for unified API
+ * 4. Returns all three as a single DbClient object
+ *
+ * Error handling:
+ * - Wraps any database initialization errors with a clear message
+ * - Preserves the original error as `cause` property
+ *
+ * Schema caching:
+ * - Uses the same caching mechanism as getSchema()
+ * - Multiple calls to getDbClient() will return the same schema reference
+ *
+ * @returns Promise<DbClient> Unified client with db, schema, and raw
+ * @throws {Error} When database initialization fails, with cause attached
+ *
+ * @example
+ * ```typescript
+ * const { db, schema, raw } = await getDbClient();
+ *
+ * // Use db for queries
+ * const memories = await db.select().from(schema.memories).limit(10);
+ *
+ * // Use raw for special cases
+ * const client = (raw as any).$client;
+ * if (client && typeof client.exec === 'function') {
+ *   client.exec('VACUUM');
+ * }
+ * ```
+ */
+export async function getDbClient() {
+    try {
+        // Get raw database connection
+        const rawDb = await getDb();
+        // Get schema (with caching)
+        if (!cachedSchema) {
+            cachedSchema = await getSchema();
+        }
+        // Create wrapped database client
+        const db = createDatabaseClient(rawDb);
+        return {
+            db,
+            schema: cachedSchema,
+            raw: rawDb,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error
+            ? `Database initialization failed: ${error.message}`
+            : 'Database initialization failed';
+        // Wrap error with clear message while preserving cause
+        const wrappedError = new Error(message);
+        // @ts-ignore - TypeScript doesn't allow 'cause' on Error, but it's valid
+        wrappedError.cause = error;
+        throw wrappedError;
+    }
+}
+/**
+ * Execute an operation with a unified database client.
+ *
+ * Convenience wrapper that:
+ * 1. Calls getDbClient() to obtain client
+ * 2. Executes the provided operation
+ * 3. Ensures proper cleanup if needed (no-op currently, for future extension)
+ *
+ * @param operation - Async function that receives the DbClient and returns a result
+ * @returns Promise<T> The result returned by the operation
+ * @throws {Error} When database initialization or operation fails
+ *
+ * @example
+ * ```typescript
+ * const count = await withDbClient(async (client) => {
+ *   const result = await client.db
+ *     .select({ count: sql`count(*)` })
+ *     .from(client.schema.memories);
+ *   return result[0].count;
+ * });
+ * ```
+ */
+export async function withDbClient(operation) {
+    const client = await getDbClient();
+    try {
+        return await operation(client);
+    }
+    finally {
+        // Future: Add cleanup logic if needed (connection pooling, etc.)
+        // Currently getDb() handles connection pooling and reuse
+    }
+}
+//# sourceMappingURL=db-client.js.map

package/dist/core/lib/schemas.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Shared Zod schemas for input validation across Squish
+ * Provides consistent validation for common input types
+ */
+import { z } from 'zod';
+/**
+ * Limit schema: integer between 1 and 100, default 20
+ */
+export declare const limitSchema: z.ZodDefault<z.ZodNumber>;
+/**
+ * Offset schema: integer >= 0, default 0
+ */
+export declare const offsetSchema: z.ZodDefault<z.ZodNumber>;
+/**
+ * Project ID/path schema: non-empty string
+ */
+export declare const projectIdSchema: z.ZodString;
+/**
+ * Memory ID schema: valid UUID
+ */
+export declare const memoryIdSchema: z.ZodString;
+/**
+ * Pagination schema combining limit and offset
+ */
+export declare const paginationSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    offset: number;
+}, {
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
+/**
+ * Search query schema: non-empty string
+ */
+export declare const searchQuerySchema: z.ZodString;
+/**
+ * Memory type schema
+ */
+export declare const memoryTypeSchema: z.ZodEnum<["observation", "fact", "decision", "context", "preference", "note"]>;
+/**
+ * Association type schema
+ */
+export declare const associationTypeSchema: z.ZodEnum<["relates_to", "supports", "contradicts", "supersedes", "duplicate"]>;
+/**
+ * Weight schema: number between 0 and 1
+ */
+export declare const weightSchema: z.ZodNumber;
+/**
+ * Learning type schema
+ */
+export declare const learningTypeSchema: z.ZodEnum<["success", "failure", "fix", "observation"]>;
+/**
+ * Observation type schema
+ */
+export declare const observationTypeSchema: z.ZodEnum<["tool_use", "file_change", "error", "pattern", "insight"]>;
+/**
+ * Confidence level schema
+ */
+export declare const confidenceLevelSchema: z.ZodEnum<["certain", "speculative", "outdated"]>;
+/**
+ * Search input schema (common for search operations)
+ */
+export declare const searchInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    offset: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    project: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<["observation", "fact", "decision", "context", "preference", "note"]>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    project?: string | undefined;
+    type?: "observation" | "fact" | "decision" | "context" | "preference" | "note" | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}, {
+    query: string;
+    project?: string | undefined;
+    type?: "observation" | "fact" | "decision" | "context" | "preference" | "note" | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
+/**
+ * Memory recall schema
+ */
+export declare const recallInputSchema: z.ZodObject<{
+    memoryId: z.ZodString;
+    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    project: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    memoryId: string;
+    project?: string | undefined;
+    limit?: number | undefined;
+}, {
+    memoryId: string;
+    project?: string | undefined;
+    limit?: number | undefined;
+}>;
+/**
+ * Tag operation schema
+ */
+export declare const tagOperationSchema: z.ZodObject<{
+    action: z.ZodEnum<["add", "remove"]>;
+    tag: z.ZodString;
+    search: z.ZodOptional<z.ZodString>;
+    olderThan: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodEnum<["observation", "fact", "decision", "context", "preference", "note"]>>;
+    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    project: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: "add" | "remove";
+    tag: string;
+    search?: string | undefined;
+    project?: string | undefined;
+    type?: "observation" | "fact" | "decision" | "context" | "preference" | "note" | undefined;
+    limit?: number | undefined;
+    olderThan?: string | undefined;
+}, {
+    action: "add" | "remove";
+    tag: string;
+    search?: string | undefined;
+    project?: string | undefined;
+    type?: "observation" | "fact" | "decision" | "context" | "preference" | "note" | undefined;
+    limit?: number | undefined;
+    olderThan?: string | undefined;
+}>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/core/lib/schemas.js

@@ -0,0 +1,87 @@
+/**
+ * Shared Zod schemas for input validation across Squish
+ * Provides consistent validation for common input types
+ */
+import { z } from 'zod';
+/**
+ * Limit schema: integer between 1 and 100, default 20
+ */
+export const limitSchema = z.number().int().min(1).max(100).default(20);
+/**
+ * Offset schema: integer >= 0, default 0
+ */
+export const offsetSchema = z.number().int().min(0).default(0);
+/**
+ * Project ID/path schema: non-empty string
+ */
+export const projectIdSchema = z.string().min(1);
+/**
+ * Memory ID schema: valid UUID
+ */
+export const memoryIdSchema = z.string().uuid();
+/**
+ * Pagination schema combining limit and offset
+ */
+export const paginationSchema = z.object({
+    limit: limitSchema,
+    offset: offsetSchema,
+});
+/**
+ * Search query schema: non-empty string
+ */
+export const searchQuerySchema = z.string().min(1).trim();
+/**
+ * Memory type schema
+ */
+export const memoryTypeSchema = z.enum(['observation', 'fact', 'decision', 'context', 'preference', 'note']);
+/**
+ * Association type schema
+ */
+export const associationTypeSchema = z.enum(['relates_to', 'supports', 'contradicts', 'supersedes', 'duplicate']);
+/**
+ * Weight schema: number between 0 and 1
+ */
+export const weightSchema = z.number().min(0).max(1);
+/**
+ * Learning type schema
+ */
+export const learningTypeSchema = z.enum(['success', 'failure', 'fix', 'observation']);
+/**
+ * Observation type schema
+ */
+export const observationTypeSchema = z.enum(['tool_use', 'file_change', 'error', 'pattern', 'insight']);
+/**
+ * Confidence level schema
+ */
+export const confidenceLevelSchema = z.enum(['certain', 'speculative', 'outdated']);
+/**
+ * Search input schema (common for search operations)
+ */
+export const searchInputSchema = z.object({
+    query: searchQuerySchema,
+    limit: limitSchema.optional(),
+    offset: offsetSchema.optional(),
+    project: projectIdSchema.optional(),
+    type: memoryTypeSchema.optional(),
+});
+/**
+ * Memory recall schema
+ */
+export const recallInputSchema = z.object({
+    memoryId: memoryIdSchema,
+    limit: limitSchema.optional(),
+    project: projectIdSchema.optional(),
+});
+/**
+ * Tag operation schema
+ */
+export const tagOperationSchema = z.object({
+    action: z.enum(['add', 'remove']),
+    tag: z.string().min(1),
+    search: z.string().optional(),
+    olderThan: z.string().optional(),
+    type: memoryTypeSchema.optional(),
+    limit: limitSchema.optional(),
+    project: projectIdSchema.optional(),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/core/{utils.d.ts → lib/utils.d.ts}

@@ -2,6 +2,7 @@
  * Shared utility functions for the squish codebase
  */
 export declare function normalizeTimestamp(value: any): string | null;
+export declare function now(): string;
 export declare function isDatabaseUnavailableError(error: any): boolean;
 export declare function withDatabaseErrorHandling<T>(operation: () => Promise<T>, errorMessage: string): Promise<T>;
 export declare function clampLimit(value: number | undefined, defaultValue: number, min?: number, max?: number): number;

package/dist/core/{utils.js → lib/utils.js}

@@ -2,8 +2,8 @@
  * Shared utility functions for the squish codebase
  */
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { config } from '../config.js';
-import { toSqliteJson } from './memory/serialization.js';
+import { config } from '../../config.js';
+import { toSqliteJson } from '../memory/serialization.js';
 export function normalizeTimestamp(value) {
     if (!value)
         return null;
@@ -11,15 +11,20 @@ export function normalizeTimestamp(value) {
         return value.toISOString();
     if (typeof value === 'number') {
         try {
-            const date = new Date(value);
-            if (!isNaN(date.getTime()))
-                return date.toISOString();
-            const dateSec = new Date(value * 1000);
-            if (!isNaN(dateSec.getTime()))
-                return dateSec.toISOString();
-            const dateMs = new Date(value / 1000);
-            if (!isNaN(dateMs.getTime()))
-                return dateMs.toISOString();
+            // Handle different timestamp formats using magnitude thresholds
+            // Microseconds: > 100000000000000 (e.g., 1700000000000000)
+            // Milliseconds: > 1000000000000 (e.g., 1700000000000)
+            // Seconds: <= 1000000000000 (e.g., 1700000000)
+            if (value > 100000000000000) {
+                return new Date(value / 1000).toISOString();
+            }
+            else if (value > 1000000000000) {
+                return new Date(value).toISOString();
+            }
+            else if (value >= 0) {
+                return new Date(value * 1000).toISOString();
+            }
+            return null;
         }
         catch {
             return null;
@@ -30,17 +35,28 @@ export function normalizeTimestamp(value) {
             const parsed = new Date(value);
             if (!isNaN(parsed.getTime()))
                 return parsed.toISOString();
+            return null;
         }
         catch {
-            return value;
+            return null;
         }
-        return value;
     }
     return null;
 }
+export function now() {
+    return new Date().toISOString();
+}
 export function isDatabaseUnavailableError(error) {
-    return error.message?.includes('Database unavailable') ||
-        error.message?.includes('not a valid Win32 application');
+    const message = error?.message || '';
+    return [
+        'Database unavailable',
+        'not a valid Win32 application',
+        'invalid ELF header',
+        'bun:',
+        'sql.js wasm asset not found',
+        'SQLite database initialization failed',
+        'working local SQLite driver',
+    ].some((pattern) => message.includes(pattern));
 }
 export async function withDatabaseErrorHandling(operation, errorMessage) {
     try {

package/dist/core/lib/validation.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Input validation utilities for Squish
+ * Consolidates scattered validation patterns into a unified module
+ */
+import { normalizeTags } from '../memory/serialization.js';
+/**
+ * Validate and normalize a limit value with bounds checking
+ */
+export declare function validateLimit(value: number | string | undefined, defaultValue?: number, min?: number, max?: number): number;
+/**
+ * Parse an integer with bounds checking
+ */
+export declare function parseIntBounded(value: number | string | undefined, defaultValue: number, min: number, max: number): number;
+/**
+ * Validate a project path
+ */
+export declare function validateProjectPath(path: string | undefined, options?: {
+    createIfMissing?: boolean;
+    require?: boolean;
+}): Promise<string>;
+/**
+ * Validate a UUID
+ */
+export declare function validateUuid(id: string): boolean;
+/**
+ * Require a valid UUID, throws if invalid
+ */
+export declare function requireUuid(id: string): string;
+/**
+ * Validate a date value
+ *
+ * @param value - The date to validate (string, Date, number, or undefined)
+ * @returns Date object if valid, null otherwise
+ */
+export declare function validateDate(value: string | Date | number | undefined): Date | null;
+export { normalizeTags };
+export { clampLimit } from './utils.js';
+//# sourceMappingURL=validation.d.ts.map