claude-cognitive 0.1.0

package/dist/config.js

@@ -0,0 +1,264 @@
+/**
+ * Configuration loading for claude-cognitive.
+ * @module config
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Default configuration values.
+ */
+const DEFAULT_CONFIG = {
+    hindsight: {
+        host: "localhost",
+        port: 8888,
+        timeout: 10000,
+    },
+    semantic: {
+        path: ".claude/memory.md",
+    },
+};
+/**
+ * Check if a value is a plain object (not array, null, etc.).
+ * @internal
+ */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Deep merge configuration objects.
+ * @internal
+ */
+function mergeConfig(target, source) {
+    const result = {
+        hindsight: { ...target.hindsight },
+    };
+    // Copy optional fields from target only if defined
+    if (target.semantic !== undefined) {
+        result.semantic = { ...target.semantic };
+    }
+    if (target.bankId !== undefined) {
+        result.bankId = target.bankId;
+    }
+    if (target.disposition !== undefined) {
+        result.disposition = target.disposition;
+    }
+    if (target.background !== undefined) {
+        result.background = target.background;
+    }
+    // Merge hindsight settings
+    if (source.hindsight) {
+        if (source.hindsight.host !== undefined) {
+            result.hindsight.host = source.hindsight.host;
+        }
+        if (source.hindsight.port !== undefined) {
+            result.hindsight.port = source.hindsight.port;
+        }
+        if (source.hindsight.apiKey !== undefined) {
+            result.hindsight.apiKey = source.hindsight.apiKey;
+        }
+        if (source.hindsight.timeout !== undefined) {
+            result.hindsight.timeout = source.hindsight.timeout;
+        }
+    }
+    // Merge semantic settings
+    if (source.semantic) {
+        if (!result.semantic) {
+            result.semantic = { path: ".claude/memory.md" };
+        }
+        if (source.semantic.path !== undefined) {
+            result.semantic.path = source.semantic.path;
+        }
+    }
+    // Merge top-level optional fields
+    if (source.bankId !== undefined) {
+        result.bankId = source.bankId;
+    }
+    if (source.disposition !== undefined) {
+        result.disposition = source.disposition;
+    }
+    if (source.background !== undefined) {
+        result.background = source.background;
+    }
+    return result;
+}
+/**
+ * Safely read and parse a JSON file.
+ * Returns undefined if file doesn't exist or is invalid JSON.
+ * @internal
+ */
+async function readJsonFile(path) {
+    try {
+        const content = await readFile(path, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Load configuration from package.json "claudemind" key.
+ * @internal
+ */
+async function loadPackageJsonConfig(projectPath) {
+    const pkgPath = join(projectPath, "package.json");
+    const pkg = await readJsonFile(pkgPath);
+    if (isPlainObject(pkg) && isPlainObject(pkg["claudemind"])) {
+        return pkg["claudemind"];
+    }
+    return undefined;
+}
+/**
+ * Load configuration from .claudemindrc file.
+ * @internal
+ */
+async function loadRcConfig(projectPath) {
+    const rcPath = join(projectPath, ".claudemindrc");
+    const rc = await readJsonFile(rcPath);
+    if (isPlainObject(rc)) {
+        return rc;
+    }
+    return undefined;
+}
+/**
+ * Apply environment variable overrides to config.
+ * @internal
+ */
+function applyEnvConfig(config) {
+    const result = {
+        hindsight: { ...config.hindsight },
+    };
+    // Copy optional fields from config only if defined
+    if (config.semantic !== undefined) {
+        result.semantic = { ...config.semantic };
+    }
+    if (config.bankId !== undefined) {
+        result.bankId = config.bankId;
+    }
+    if (config.disposition !== undefined) {
+        result.disposition = config.disposition;
+    }
+    if (config.background !== undefined) {
+        result.background = config.background;
+    }
+    // Hindsight connection settings
+    const host = process.env["HINDSIGHT_HOST"];
+    if (host) {
+        result.hindsight.host = host;
+    }
+    const port = process.env["HINDSIGHT_PORT"];
+    if (port) {
+        const parsed = parseInt(port, 10);
+        if (!isNaN(parsed) && parsed > 0 && parsed < 65536) {
+            result.hindsight.port = parsed;
+        }
+    }
+    const apiKey = process.env["HINDSIGHT_API_KEY"];
+    if (apiKey) {
+        result.hindsight.apiKey = apiKey;
+    }
+    // Bank settings
+    const bankId = process.env["CLAUDEMIND_BANK_ID"];
+    if (bankId) {
+        result.bankId = bankId;
+    }
+    return result;
+}
+/**
+ * Validate disposition values are in valid range.
+ * @internal
+ */
+function validateDisposition(disposition) {
+    if (!isPlainObject(disposition)) {
+        return false;
+    }
+    const traits = ["skepticism", "literalism", "empathy"];
+    for (const trait of traits) {
+        const value = disposition[trait];
+        if (typeof value !== "number" ||
+            !Number.isInteger(value) ||
+            value < 1 ||
+            value > 5) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Clone a configuration object.
+ * @internal
+ */
+function cloneConfig(config) {
+    const result = {
+        hindsight: { ...config.hindsight },
+    };
+    if (config.semantic !== undefined) {
+        result.semantic = { ...config.semantic };
+    }
+    if (config.bankId !== undefined) {
+        result.bankId = config.bankId;
+    }
+    if (config.disposition !== undefined) {
+        result.disposition = { ...config.disposition };
+    }
+    if (config.background !== undefined) {
+        result.background = config.background;
+    }
+    return result;
+}
+/**
+ * Load configuration from multiple sources with priority order:
+ *
+ * 1. Constructor overrides (highest priority)
+ * 2. Environment variables
+ * 3. .claudemindrc file
+ * 4. package.json "claudemind" key
+ * 5. Default values (lowest priority)
+ *
+ * @param projectPath - Root directory of the project (default: process.cwd())
+ * @param overrides - Explicit configuration overrides
+ * @returns Merged configuration
+ *
+ * @example
+ * ```typescript
+ * // Load from current directory with defaults
+ * const config = await loadConfig();
+ *
+ * // Load from specific directory with overrides
+ * const config = await loadConfig('/path/to/project', {
+ *   hindsight: { host: 'hindsight.example.com' }
+ * });
+ * ```
+ */
+export async function loadConfig(projectPath = process.cwd(), overrides) {
+    // Start with defaults
+    let config = cloneConfig(DEFAULT_CONFIG);
+    // Load from package.json "claudemind" key (lowest priority file config)
+    const pkgConfig = await loadPackageJsonConfig(projectPath);
+    if (pkgConfig) {
+        config = mergeConfig(config, pkgConfig);
+    }
+    // Load from .claudemindrc (higher priority than package.json)
+    const rcConfig = await loadRcConfig(projectPath);
+    if (rcConfig) {
+        config = mergeConfig(config, rcConfig);
+    }
+    // Apply environment variables (higher priority than files)
+    config = applyEnvConfig(config);
+    // Apply explicit overrides (highest priority)
+    if (overrides) {
+        config = mergeConfig(config, overrides);
+    }
+    // Validate disposition if present
+    if (config.disposition && !validateDisposition(config.disposition)) {
+        throw new Error("Invalid disposition in configuration: values must be integers between 1 and 5");
+    }
+    return config;
+}
+/**
+ * Get default configuration without loading from files.
+ * Useful for testing or when you want explicit control.
+ */
+export function getDefaultConfig() {
+    return cloneConfig(DEFAULT_CONFIG);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Error handling for claude-cognitive Hindsight client.
+ * @module errors
+ */
+import type { HindsightErrorCode } from "./types.js";
+/**
+ * Base error class for all Hindsight-related errors.
+ *
+ * Includes error code for programmatic handling,
+ * isRetryable flag for retry logic, and preserves
+ * cause for debugging.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.recall(bankId, query);
+ * } catch (error) {
+ *   if (HindsightError.isHindsightError(error)) {
+ *     if (error.isRetryable) {
+ *       // Retry the operation
+ *     }
+ *     console.error(`Error ${error.code}: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class HindsightError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: HindsightErrorCode;
+    /** Whether this error can be retried */
+    readonly isRetryable: boolean;
+    /** HTTP status code if this was an HTTP error */
+    readonly statusCode?: number;
+    constructor(message: string, code: HindsightErrorCode, options?: {
+        cause?: Error;
+        isRetryable?: boolean;
+        statusCode?: number;
+    });
+    /**
+     * Type guard to check if an error is a HindsightError.
+     */
+    static isHindsightError(error: unknown): error is HindsightError;
+    /** Check if Hindsight server is unavailable */
+    get isUnavailable(): boolean;
+    /** Check if bank was not found */
+    get isBankNotFound(): boolean;
+    /** Check if this is a validation error */
+    get isValidationError(): boolean;
+    /** Check if this is a timeout error */
+    get isTimeout(): boolean;
+}
+/**
+ * Extract error message from an API response body.
+ * @internal
+ */
+export declare function extractErrorMessage(body: unknown): string | undefined;
+/**
+ * Parse Retry-After header value to milliseconds.
+ * @internal
+ */
+export declare function parseRetryAfter(header: string | null): number | undefined;
+/**
+ * Create a HindsightError from an HTTP response.
+ * @internal
+ */
+export declare function createErrorFromResponse(response: Response, body: unknown, path: string): HindsightError;
+/**
+ * Create a HindsightError from a network failure.
+ * @internal
+ */
+export declare function createErrorFromNetworkFailure(error: Error): HindsightError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAElC,wCAAwC;IACxC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B,iDAAiD;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAG3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,kBAAkB,EACxB,OAAO,GAAE;QACP,KAAK,CAAC,EAAE,KAAK,CAAC;QACd,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KAChB;IAeR;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc;IAIhE,+CAA+C;IAC/C,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,kCAAkC;IAClC,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,0CAA0C;IAC1C,IAAI,iBAAiB,IAAI,OAAO,CAI/B;IAED,uCAAuC;IACvC,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAgBrE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAmBzE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,GACX,cAAc,CAkFhB;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,KAAK,GAAG,cAAc,CAsC1E"}

package/dist/errors.js

@@ -0,0 +1,188 @@
+/**
+ * Error handling for claude-cognitive Hindsight client.
+ * @module errors
+ */
+/**
+ * Base error class for all Hindsight-related errors.
+ *
+ * Includes error code for programmatic handling,
+ * isRetryable flag for retry logic, and preserves
+ * cause for debugging.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.recall(bankId, query);
+ * } catch (error) {
+ *   if (HindsightError.isHindsightError(error)) {
+ *     if (error.isRetryable) {
+ *       // Retry the operation
+ *     }
+ *     console.error(`Error ${error.code}: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+export class HindsightError extends Error {
+    /** Error code for programmatic handling */
+    code;
+    /** Whether this error can be retried */
+    isRetryable;
+    /** HTTP status code if this was an HTTP error */
+    statusCode;
+    constructor(message, code, options = {}) {
+        super(message, { cause: options.cause });
+        // Fix prototype chain for instanceof checks
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = "HindsightError";
+        this.code = code;
+        this.isRetryable = options.isRetryable ?? false;
+        if (options.statusCode !== undefined) {
+            this.statusCode = options.statusCode;
+        }
+    }
+    /**
+     * Type guard to check if an error is a HindsightError.
+     */
+    static isHindsightError(error) {
+        return error instanceof HindsightError;
+    }
+    /** Check if Hindsight server is unavailable */
+    get isUnavailable() {
+        return this.code === "HINDSIGHT_UNAVAILABLE";
+    }
+    /** Check if bank was not found */
+    get isBankNotFound() {
+        return this.code === "BANK_NOT_FOUND";
+    }
+    /** Check if this is a validation error */
+    get isValidationError() {
+        return (this.code === "VALIDATION_ERROR" || this.code === "INVALID_DISPOSITION");
+    }
+    /** Check if this is a timeout error */
+    get isTimeout() {
+        return this.code === "CONNECTION_TIMEOUT";
+    }
+}
+/**
+ * Extract error message from an API response body.
+ * @internal
+ */
+export function extractErrorMessage(body) {
+    if (body === null || body === undefined) {
+        return undefined;
+    }
+    if (typeof body === "object") {
+        const obj = body;
+        if (typeof obj["message"] === "string") {
+            return obj["message"];
+        }
+        if (typeof obj["error"] === "string") {
+            return obj["error"];
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse Retry-After header value to milliseconds.
+ * @internal
+ */
+export function parseRetryAfter(header) {
+    if (!header) {
+        return undefined;
+    }
+    // Try parsing as seconds (integer)
+    const seconds = parseInt(header, 10);
+    if (!isNaN(seconds)) {
+        return seconds * 1000;
+    }
+    // Try parsing as HTTP date
+    const date = Date.parse(header);
+    if (!isNaN(date)) {
+        const delay = date - Date.now();
+        return delay > 0 ? delay : undefined;
+    }
+    return undefined;
+}
+/**
+ * Create a HindsightError from an HTTP response.
+ * @internal
+ */
+export function createErrorFromResponse(response, body, path) {
+    const status = response.status;
+    const message = extractErrorMessage(body) || response.statusText || "Request failed";
+    switch (status) {
+        case 400:
+            return new HindsightError(`Bad request: ${message}`, "VALIDATION_ERROR", {
+                statusCode: status,
+                isRetryable: false,
+            });
+        case 401:
+        case 403:
+            return new HindsightError(`Authentication failed: ${message}`, "VALIDATION_ERROR", { statusCode: status, isRetryable: false });
+        case 404:
+            // Check if this is a bank not found error
+            if (path.includes("/banks/")) {
+                return new HindsightError(`Bank not found: ${message}`, "BANK_NOT_FOUND", {
+                    statusCode: 404,
+                    isRetryable: false,
+                });
+            }
+            return new HindsightError(`Not found: ${message}`, "VALIDATION_ERROR", {
+                statusCode: 404,
+                isRetryable: false,
+            });
+        case 422:
+            // Check if this is a disposition validation error
+            if (message.toLowerCase().includes("disposition")) {
+                return new HindsightError(`Invalid disposition: ${message}`, "INVALID_DISPOSITION", { statusCode: 422, isRetryable: false });
+            }
+            return new HindsightError(`Validation failed: ${message}`, "VALIDATION_ERROR", { statusCode: 422, isRetryable: false });
+        case 429:
+            return new HindsightError(`Rate limited: ${message}`, "RATE_LIMITED", {
+                statusCode: 429,
+                isRetryable: true,
+            });
+        case 500:
+        case 502:
+        case 503:
+        case 504:
+            return new HindsightError(`Server error (${status}): ${message}`, "SERVER_ERROR", { statusCode: status, isRetryable: true });
+        default:
+            if (status >= 500) {
+                return new HindsightError(`Server error (${status}): ${message}`, "SERVER_ERROR", { statusCode: status, isRetryable: true });
+            }
+            return new HindsightError(`HTTP error (${status}): ${message}`, "UNKNOWN_ERROR", { statusCode: status, isRetryable: false });
+    }
+}
+/**
+ * Create a HindsightError from a network failure.
+ * @internal
+ */
+export function createErrorFromNetworkFailure(error) {
+    // Timeout via AbortSignal.timeout()
+    if (error.name === "TimeoutError") {
+        return new HindsightError("Request timed out", "CONNECTION_TIMEOUT", {
+            cause: error,
+            isRetryable: true,
+        });
+    }
+    // User-initiated abort
+    if (error.name === "AbortError") {
+        return new HindsightError("Request was cancelled", "UNKNOWN_ERROR", {
+            cause: error,
+            isRetryable: false,
+        });
+    }
+    // Network failure (DNS, connection refused, etc.)
+    const message = error.message.toLowerCase();
+    if (message.includes("econnrefused") ||
+        message.includes("enotfound") ||
+        message.includes("fetch failed") ||
+        message.includes("network")) {
+        return new HindsightError("Cannot connect to Hindsight server", "HINDSIGHT_UNAVAILABLE", { cause: error, isRetryable: true });
+    }
+    // Unknown error
+    return new HindsightError(`Network error: ${error.message}`, "HINDSIGHT_UNAVAILABLE", { cause: error, isRetryable: true });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}