causantic 0.2.0

package/dist/utils/embedding-utils.js

@@ -0,0 +1,30 @@
+/**
+ * Shared embedding serialization utilities.
+ * Used by vector-store and embedding-cache for SQLite BLOB storage.
+ */
+/**
+ * Serialize an embedding to a Buffer for SQLite storage.
+ *
+ * Uses Float32Array for efficient storage (4 bytes per dimension).
+ * A 1024-dimension embedding uses 4KB of storage.
+ *
+ * @param embedding - Array of floating point values
+ * @returns Buffer containing Float32Array binary representation
+ */
+export function serializeEmbedding(embedding) {
+    return Buffer.from(new Float32Array(embedding).buffer);
+}
+/**
+ * Deserialize an embedding from a SQLite Buffer.
+ *
+ * Reconstructs the Float32Array from the raw buffer bytes,
+ * handling byte offset alignment properly.
+ *
+ * @param buffer - Buffer from SQLite BLOB column
+ * @returns Array of floating point values
+ */
+export function deserializeEmbedding(buffer) {
+    const float32 = new Float32Array(buffer.buffer, buffer.byteOffset, buffer.length / Float32Array.BYTES_PER_ELEMENT);
+    return Array.from(float32);
+}
+//# sourceMappingURL=embedding-utils.js.map

package/dist/utils/embedding-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-utils.js","sourceRoot":"","sources":["../../src/utils/embedding-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAmB;IACpD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,MAAM,OAAO,GAAG,IAAI,YAAY,CAC9B,MAAM,CAAC,MAAM,EACb,MAAM,CAAC,UAAU,EACjB,MAAM,CAAC,MAAM,GAAG,YAAY,CAAC,iBAAiB,CAC/C,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Standardized error types for Causantic.
+ *
+ * All errors extend from CausanticError, providing:
+ * - Error code for programmatic handling
+ * - Cause chaining for debugging
+ * - Consistent error messages
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { StorageError, IngestionError } from './errors.js';
+ *
+ * // Throw a storage error
+ * throw new StorageError('Database connection failed', 'DB_CONNECTION_FAILED');
+ *
+ * // Chain errors
+ * try {
+ *   await someOperation();
+ * } catch (err) {
+ *   throw new IngestionError('Session ingestion failed', 'INGEST_FAILED', err);
+ * }
+ * ```
+ *
+ * @module utils/errors
+ */
+/**
+ * Base error class for all Causantic errors.
+ *
+ * Provides:
+ * - `code`: Programmatic error identifier (e.g., 'DB_CONNECTION_FAILED')
+ * - `cause`: Original error that caused this one (for chaining)
+ * - `name`: Error class name (e.g., 'StorageError')
+ */
+export declare class CausanticError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    /** Original error that caused this one */
+    readonly cause?: Error;
+    constructor(message: string, code: string, cause?: unknown);
+    /**
+     * Get a formatted string including cause chain.
+     */
+    toDetailedString(): string;
+}
+/**
+ * Errors from the storage layer (database, vector store, etc).
+ *
+ * Common codes:
+ * - `DB_CONNECTION_FAILED`: Cannot connect to database
+ * - `DB_QUERY_FAILED`: Query execution failed
+ * - `CHUNK_NOT_FOUND`: Requested chunk doesn't exist
+ * - `EDGE_NOT_FOUND`: Requested edge doesn't exist
+ * - `VECTOR_INSERT_FAILED`: Failed to insert vector embedding
+ * - `VECTOR_SEARCH_FAILED`: Vector similarity search failed
+ */
+export declare class StorageError extends CausanticError {
+    constructor(message: string, code: string, cause?: unknown);
+}
+/**
+ * Errors during session ingestion.
+ *
+ * Common codes:
+ * - `SESSION_READ_FAILED`: Cannot read session file
+ * - `PARSE_FAILED`: Failed to parse session messages
+ * - `CHUNK_FAILED`: Chunking process failed
+ * - `EMBED_FAILED`: Embedding generation failed
+ * - `EDGE_DETECTION_FAILED`: Transition detection failed
+ * - `BATCH_INGEST_FAILED`: Batch ingestion encountered errors
+ */
+export declare class IngestionError extends CausanticError {
+    constructor(message: string, code: string, cause?: unknown);
+}
+/**
+ * Errors during memory retrieval.
+ *
+ * Common codes:
+ * - `TRAVERSAL_FAILED`: Graph traversal failed
+ * - `VECTOR_SEARCH_FAILED`: Vector similarity search failed
+ * - `CONTEXT_ASSEMBLY_FAILED`: Context assembly failed
+ * - `NO_EMBEDDER`: No embedder loaded for query embedding
+ * - `QUERY_TIMEOUT`: Query exceeded time limit
+ */
+export declare class RetrievalError extends CausanticError {
+    constructor(message: string, code: string, cause?: unknown);
+}
+/**
+ * Errors in configuration loading or validation.
+ *
+ * Common codes:
+ * - `CONFIG_NOT_FOUND`: Configuration file not found
+ * - `CONFIG_PARSE_FAILED`: Failed to parse configuration
+ * - `CONFIG_INVALID`: Configuration validation failed
+ * - `MISSING_REQUIRED`: Required field missing
+ * - `INVALID_VALUE`: Field value is invalid
+ */
+export declare class ConfigError extends CausanticError {
+    constructor(message: string, code: string, cause?: unknown);
+}
+/**
+ * Errors during clustering operations.
+ *
+ * Common codes:
+ * - `CLUSTER_FAILED`: HDBSCAN clustering failed
+ * - `NO_VECTORS`: No vectors available for clustering
+ * - `CENTROID_FAILED`: Centroid computation failed
+ * - `ASSIGNMENT_FAILED`: Chunk assignment failed
+ */
+export declare class ClusterError extends CausanticError {
+    constructor(message: string, code: string, cause?: unknown);
+}
+/**
+ * Errors during hook execution.
+ *
+ * Common codes:
+ * - `HOOK_FAILED`: Hook execution failed
+ * - `HOOK_TIMEOUT`: Hook exceeded time limit
+ * - `RETRY_EXHAUSTED`: All retry attempts failed
+ */
+export declare class HookError extends CausanticError {
+    constructor(message: string, code: string, cause?: unknown);
+}
+/**
+ * Check if an error is a Causantic error with a specific code.
+ */
+export declare function isErrorWithCode(error: unknown, code: string): boolean;
+/**
+ * Check if an error is a specific type of Causantic error.
+ */
+export declare function isStorageError(error: unknown): error is StorageError;
+export declare function isIngestionError(error: unknown): error is IngestionError;
+export declare function isRetrievalError(error: unknown): error is RetrievalError;
+export declare function isConfigError(error: unknown): error is ConfigError;
+export declare function isClusterError(error: unknown): error is ClusterError;
+export declare function isHookError(error: unknown): error is HookError;
+/**
+ * Wrap an unknown error in a CausanticError.
+ *
+ * If the error is already a CausanticError, returns it unchanged.
+ * Otherwise wraps it in a new CausanticError with UNKNOWN code.
+ */
+export declare function wrapError(error: unknown, message?: string): CausanticError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;IAkB1D;;OAEG;IACH,gBAAgB,IAAI,MAAM;CAY3B;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,YAAa,SAAQ,cAAc;gBAClC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG3D;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,SAAQ,cAAc;gBACpC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG3D;AAMD;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,cAAc;gBACpC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG3D;AAMD;;;;;;;;;GASG;AACH,qBAAa,WAAY,SAAQ,cAAc;gBACjC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG3D;AAMD;;;;;;;;GAQG;AACH,qBAAa,YAAa,SAAQ,cAAc;gBAClC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG3D;AAMD;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,cAAc;gBAC/B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAG3D;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAErE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,cAAc,CAO1E"}

package/dist/utils/errors.js

@@ -0,0 +1,220 @@
+/**
+ * Standardized error types for Causantic.
+ *
+ * All errors extend from CausanticError, providing:
+ * - Error code for programmatic handling
+ * - Cause chaining for debugging
+ * - Consistent error messages
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { StorageError, IngestionError } from './errors.js';
+ *
+ * // Throw a storage error
+ * throw new StorageError('Database connection failed', 'DB_CONNECTION_FAILED');
+ *
+ * // Chain errors
+ * try {
+ *   await someOperation();
+ * } catch (err) {
+ *   throw new IngestionError('Session ingestion failed', 'INGEST_FAILED', err);
+ * }
+ * ```
+ *
+ * @module utils/errors
+ */
+/**
+ * Base error class for all Causantic errors.
+ *
+ * Provides:
+ * - `code`: Programmatic error identifier (e.g., 'DB_CONNECTION_FAILED')
+ * - `cause`: Original error that caused this one (for chaining)
+ * - `name`: Error class name (e.g., 'StorageError')
+ */
+export class CausanticError extends Error {
+    /** Error code for programmatic handling */
+    code;
+    /** Original error that caused this one */
+    cause;
+    constructor(message, code, cause) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = code;
+        // Normalize cause to Error
+        if (cause instanceof Error) {
+            this.cause = cause;
+        }
+        else if (cause !== undefined) {
+            this.cause = new Error(String(cause));
+        }
+        // Capture stack trace (V8 only)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Get a formatted string including cause chain.
+     */
+    toDetailedString() {
+        let result = `${this.name} [${this.code}]: ${this.message}`;
+        if (this.cause) {
+            result += `\n  Caused by: ${this.cause.message}`;
+            if (this.cause instanceof CausanticError) {
+                result += ` [${this.cause.code}]`;
+            }
+        }
+        return result;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Storage Errors
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Errors from the storage layer (database, vector store, etc).
+ *
+ * Common codes:
+ * - `DB_CONNECTION_FAILED`: Cannot connect to database
+ * - `DB_QUERY_FAILED`: Query execution failed
+ * - `CHUNK_NOT_FOUND`: Requested chunk doesn't exist
+ * - `EDGE_NOT_FOUND`: Requested edge doesn't exist
+ * - `VECTOR_INSERT_FAILED`: Failed to insert vector embedding
+ * - `VECTOR_SEARCH_FAILED`: Vector similarity search failed
+ */
+export class StorageError extends CausanticError {
+    constructor(message, code, cause) {
+        super(message, code, cause);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Ingestion Errors
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Errors during session ingestion.
+ *
+ * Common codes:
+ * - `SESSION_READ_FAILED`: Cannot read session file
+ * - `PARSE_FAILED`: Failed to parse session messages
+ * - `CHUNK_FAILED`: Chunking process failed
+ * - `EMBED_FAILED`: Embedding generation failed
+ * - `EDGE_DETECTION_FAILED`: Transition detection failed
+ * - `BATCH_INGEST_FAILED`: Batch ingestion encountered errors
+ */
+export class IngestionError extends CausanticError {
+    constructor(message, code, cause) {
+        super(message, code, cause);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Retrieval Errors
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Errors during memory retrieval.
+ *
+ * Common codes:
+ * - `TRAVERSAL_FAILED`: Graph traversal failed
+ * - `VECTOR_SEARCH_FAILED`: Vector similarity search failed
+ * - `CONTEXT_ASSEMBLY_FAILED`: Context assembly failed
+ * - `NO_EMBEDDER`: No embedder loaded for query embedding
+ * - `QUERY_TIMEOUT`: Query exceeded time limit
+ */
+export class RetrievalError extends CausanticError {
+    constructor(message, code, cause) {
+        super(message, code, cause);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Configuration Errors
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Errors in configuration loading or validation.
+ *
+ * Common codes:
+ * - `CONFIG_NOT_FOUND`: Configuration file not found
+ * - `CONFIG_PARSE_FAILED`: Failed to parse configuration
+ * - `CONFIG_INVALID`: Configuration validation failed
+ * - `MISSING_REQUIRED`: Required field missing
+ * - `INVALID_VALUE`: Field value is invalid
+ */
+export class ConfigError extends CausanticError {
+    constructor(message, code, cause) {
+        super(message, code, cause);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Cluster Errors
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Errors during clustering operations.
+ *
+ * Common codes:
+ * - `CLUSTER_FAILED`: HDBSCAN clustering failed
+ * - `NO_VECTORS`: No vectors available for clustering
+ * - `CENTROID_FAILED`: Centroid computation failed
+ * - `ASSIGNMENT_FAILED`: Chunk assignment failed
+ */
+export class ClusterError extends CausanticError {
+    constructor(message, code, cause) {
+        super(message, code, cause);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook Errors
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Errors during hook execution.
+ *
+ * Common codes:
+ * - `HOOK_FAILED`: Hook execution failed
+ * - `HOOK_TIMEOUT`: Hook exceeded time limit
+ * - `RETRY_EXHAUSTED`: All retry attempts failed
+ */
+export class HookError extends CausanticError {
+    constructor(message, code, cause) {
+        super(message, code, cause);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Helper Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Check if an error is a Causantic error with a specific code.
+ */
+export function isErrorWithCode(error, code) {
+    return error instanceof CausanticError && error.code === code;
+}
+/**
+ * Check if an error is a specific type of Causantic error.
+ */
+export function isStorageError(error) {
+    return error instanceof StorageError;
+}
+export function isIngestionError(error) {
+    return error instanceof IngestionError;
+}
+export function isRetrievalError(error) {
+    return error instanceof RetrievalError;
+}
+export function isConfigError(error) {
+    return error instanceof ConfigError;
+}
+export function isClusterError(error) {
+    return error instanceof ClusterError;
+}
+export function isHookError(error) {
+    return error instanceof HookError;
+}
+/**
+ * Wrap an unknown error in a CausanticError.
+ *
+ * If the error is already a CausanticError, returns it unchanged.
+ * Otherwise wraps it in a new CausanticError with UNKNOWN code.
+ */
+export function wrapError(error, message) {
+    if (error instanceof CausanticError) {
+        return error;
+    }
+    const errorMessage = message ?? (error instanceof Error ? error.message : String(error));
+    return new CausanticError(errorMessage, 'UNKNOWN', error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

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

package/dist/utils/keychain.d.ts

@@ -0,0 +1,43 @@
+/**
+ * macOS Keychain integration for secure API key storage.
+ *
+ * @deprecated Use secret-store.ts for cross-platform support.
+ * This module is maintained for backward compatibility.
+ */
+import { createSecretStore, getApiKey as getApiKeyFromStore } from './secret-store.js';
+/**
+ * Get a secret from the macOS Keychain.
+ * @param account - The account/key name (e.g., 'ANTHROPIC_API_KEY')
+ * @returns The secret value, or null if not found
+ * @deprecated Use createSecretStore().get() instead
+ */
+export declare function getFromKeychain(account: string): string | null;
+/**
+ * Store a secret in the macOS Keychain.
+ * @param account - The account/key name (e.g., 'ANTHROPIC_API_KEY')
+ * @param secret - The secret value to store
+ * @deprecated Use createSecretStore().set() instead
+ */
+export declare function setInKeychain(account: string, secret: string): void;
+/**
+ * Delete a secret from the macOS Keychain.
+ * @param account - The account/key name to delete
+ * @returns true if deleted, false if not found
+ * @deprecated Use createSecretStore().delete() instead
+ */
+export declare function deleteFromKeychain(account: string): boolean;
+/**
+ * Get API key from Keychain or environment variable.
+ * Checks environment variable first, then falls back to Keychain.
+ * @param keyName - The key name (e.g., 'ANTHROPIC_API_KEY')
+ * @returns The API key, or null if not found
+ */
+export declare function getApiKey(keyName: string): string | null;
+/**
+ * Get API key using the cross-platform secret store.
+ * @param keyName - The key name (e.g., 'anthropic')
+ * @returns The API key, or null if not found
+ */
+export declare function getApiKeyAsync(keyName: string): Promise<string | null>;
+export { createSecretStore, getApiKeyFromStore };
+//# sourceMappingURL=keychain.d.ts.map

package/dist/utils/keychain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keychain.d.ts","sourceRoot":"","sources":["../../src/utils/keychain.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,iBAAiB,EAAE,SAAS,IAAI,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAIvF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU9D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAenE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAS3D;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASxD;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE5E;AAGD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/utils/keychain.js

@@ -0,0 +1,82 @@
+/**
+ * macOS Keychain integration for secure API key storage.
+ *
+ * @deprecated Use secret-store.ts for cross-platform support.
+ * This module is maintained for backward compatibility.
+ */
+import { execSync } from 'node:child_process';
+import { createSecretStore, getApiKey as getApiKeyFromStore } from './secret-store.js';
+const SERVICE_NAME = 'causantic';
+/**
+ * Get a secret from the macOS Keychain.
+ * @param account - The account/key name (e.g., 'ANTHROPIC_API_KEY')
+ * @returns The secret value, or null if not found
+ * @deprecated Use createSecretStore().get() instead
+ */
+export function getFromKeychain(account) {
+    try {
+        const result = execSync(`security find-generic-password -a "${account}" -s "${SERVICE_NAME}" -w 2>/dev/null`, { encoding: 'utf-8' });
+        return result.trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Store a secret in the macOS Keychain.
+ * @param account - The account/key name (e.g., 'ANTHROPIC_API_KEY')
+ * @param secret - The secret value to store
+ * @deprecated Use createSecretStore().set() instead
+ */
+export function setInKeychain(account, secret) {
+    // Delete existing entry if present (ignore errors)
+    try {
+        execSync(`security delete-generic-password -a "${account}" -s "${SERVICE_NAME}" 2>/dev/null`);
+    }
+    catch {
+        // Ignore - entry may not exist
+    }
+    // Add new entry
+    execSync(`security add-generic-password -a "${account}" -s "${SERVICE_NAME}" -w "${secret}"`, { encoding: 'utf-8' });
+}
+/**
+ * Delete a secret from the macOS Keychain.
+ * @param account - The account/key name to delete
+ * @returns true if deleted, false if not found
+ * @deprecated Use createSecretStore().delete() instead
+ */
+export function deleteFromKeychain(account) {
+    try {
+        execSync(`security delete-generic-password -a "${account}" -s "${SERVICE_NAME}" 2>/dev/null`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get API key from Keychain or environment variable.
+ * Checks environment variable first, then falls back to Keychain.
+ * @param keyName - The key name (e.g., 'ANTHROPIC_API_KEY')
+ * @returns The API key, or null if not found
+ */
+export function getApiKey(keyName) {
+    // Check environment variable first
+    const envValue = process.env[keyName];
+    if (envValue) {
+        return envValue;
+    }
+    // Fall back to Keychain
+    return getFromKeychain(keyName);
+}
+/**
+ * Get API key using the cross-platform secret store.
+ * @param keyName - The key name (e.g., 'anthropic')
+ * @returns The API key, or null if not found
+ */
+export async function getApiKeyAsync(keyName) {
+    return getApiKeyFromStore(keyName);
+}
+// Re-export the new API for migration
+export { createSecretStore, getApiKeyFromStore };
+//# sourceMappingURL=keychain.js.map

package/dist/utils/keychain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keychain.js","sourceRoot":"","sources":["../../src/utils/keychain.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,SAAS,IAAI,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvF,MAAM,YAAY,GAAG,WAAW,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CACrB,sCAAsC,OAAO,SAAS,YAAY,kBAAkB,EACpF,EAAE,QAAQ,EAAE,OAAO,EAAE,CACtB,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,MAAc;IAC3D,mDAAmD;IACnD,IAAI,CAAC;QACH,QAAQ,CACN,wCAAwC,OAAO,SAAS,YAAY,eAAe,CACpF,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,+BAA+B;IACjC,CAAC;IAED,gBAAgB;IAChB,QAAQ,CACN,qCAAqC,OAAO,SAAS,YAAY,SAAS,MAAM,GAAG,EACnF,EAAE,QAAQ,EAAE,OAAO,EAAE,CACtB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,IAAI,CAAC;QACH,QAAQ,CACN,wCAAwC,OAAO,SAAS,YAAY,eAAe,CACpF,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,mCAAmC;IACnC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,wBAAwB;IACxB,OAAO,eAAe,CAAC,OAAO,CAAC,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAe;IAClD,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC;AAED,sCAAsC;AACtC,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Centralized logging for Causantic.
+ *
+ * Provides structured logging with levels, metadata, and output formatting.
+ * Writes to stderr to avoid interfering with stdio-based protocols.
+ *
+ * Log level is controlled via:
+ * 1. CAUSANTIC_LOG_LEVEL environment variable
+ * 2. setLogLevel() function
+ *
+ * Levels (in order of severity): debug < info < warn < error
+ */
+/** Log level type */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/** Log entry structure */
+export interface LogEntry {
+    timestamp: string;
+    level: Exclude<LogLevel, 'silent'>;
+    message: string;
+    meta?: Record<string, unknown>;
+}
+/** Logger interface */
+export interface Logger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Set the log level.
+ */
+export declare function setLogLevel(level: LogLevel): void;
+/**
+ * Get the current log level.
+ */
+export declare function getLogLevel(): LogLevel;
+/**
+ * Enable or disable JSON output mode.
+ */
+export declare function setJsonMode(enabled: boolean): void;
+/**
+ * Main logger instance.
+ */
+export declare const logger: Logger;
+/**
+ * Create a child logger with a fixed prefix.
+ */
+export declare function createLogger(prefix: string): Logger;
+export default logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,qBAAqB;AACrB,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtE,0BAA0B;AAC1B,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,uBAAuB;AACvB,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AAiBD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAElD;AAiDD;;GAEG;AACH,eAAO,MAAM,MAAM,EAAE,MAKpB,CAAC;AAEF;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOnD;AAGD,eAAe,MAAM,CAAC"}