@yeseh/cortex-cli 0.6.8 → 0.6.9

package/src/context.spec.ts

@@ -1,60 +0,0 @@
-/**
- * Unit tests for create-cli-command.ts — validateStorePath.
- *
- * Verifies that absolute paths pass validation and relative paths
- * produce a typed INVALID_STORE_PATH error result.
- *
- * @module cli/create-cli-command.spec
- */
-
-import { describe, it, expect } from 'bun:test';
-
-import { validateStorePath } from './context.ts';
-
-describe('validateStorePath', () => {
-    it('should return ok for a Unix absolute path', () => {
-        const result = validateStorePath('/home/user/.cortex/memory', 'my-store');
-        expect(result.ok()).toBe(true);
-    });
-
-    it('should return ok for a Windows-style absolute path', () => {
-        // isAbsolute on Linux treats "C:\\..." as relative, but a UNC-style
-        // or drive-letter path on Windows would be absolute. We test with a
-        // typical Unix absolute path variant to keep cross-platform coverage.
-        const result = validateStorePath('/var/cortex/stores/global', 'global');
-        expect(result.ok()).toBe(true);
-    });
-
-    it('should return INVALID_STORE_PATH for a relative path', () => {
-        const result = validateStorePath('relative/path/to/store', 'my-store');
-        expect(result.ok()).toBe(false);
-        if (!result.ok()) {
-            expect(result.error.code).toBe('INVALID_STORE_PATH');
-        }
-    });
-
-    it('should return INVALID_STORE_PATH for a path starting with ./', () => {
-        const result = validateStorePath('./local/store', 'my-store');
-        expect(result.ok()).toBe(false);
-        if (!result.ok()) {
-            expect(result.error.code).toBe('INVALID_STORE_PATH');
-        }
-    });
-
-    it('should include the store name in the error message', () => {
-        const storeName = 'my-named-store';
-        const result = validateStorePath('not/absolute', storeName);
-        expect(result.ok()).toBe(false);
-        if (!result.ok()) {
-            expect(result.error.message).toContain(storeName);
-        }
-    });
-
-    it('should return INVALID_STORE_PATH for empty string', () => {
-        const result = validateStorePath('', 'some-store');
-        expect(result.ok()).toBe(false);
-        if (!result.ok()) {
-            expect(result.error.code).toBe('INVALID_STORE_PATH');
-        }
-    });
-});

package/src/context.ts

@@ -1,170 +0,0 @@
-import {
-    Cortex,
-    err,
-    getDefaultSettings,
-    ok,
-    type ConfigValidationError,
-    type CortexContext,
-    type Result,
-} from '@yeseh/cortex-core';
-import { homedir } from 'os';
-import { isAbsolute, resolve } from 'path';
-import { FilesystemStorageAdapter, FilesystemConfigAdapter } from '@yeseh/cortex-storage-fs';
-import { stdin, stdout } from 'process';
-import { createCliLogger } from './observability.ts';
-
-// TODO: Much of this module should move to the FS adapter, since it's all about loading config from the filesystem. The CLI command handlers should just call into the core module to load config and create a context, rather than having all the logic here.
-
-const makeAbsolute = (pathStr: string): string => {
-    if (pathStr.startsWith('~')) {
-        return resolve(homedir(), pathStr.slice(1).replace(/^[/\\]/, ''));
-    }
-    return isAbsolute(pathStr) ? pathStr : resolve(pathStr);
-};
-
-export const validateStorePath = (
-    storePath: string,
-    storeName: string
-): Result<void, ConfigValidationError> => {
-    if (!isAbsolute(storePath)) {
-        return err({
-            code: 'INVALID_STORE_PATH',
-            message:
-                `Store '${storeName}' path must be absolute. Got: ${storePath}. ` +
-                "Use an absolute path like '/home/user/.cortex/memory'.",
-            store: storeName,
-        });
-    }
-    return ok(undefined);
-};
-
-export interface ConfigLoadOptions {
-    cwd?: string;
-    globalConfigPath?: string;
-    localConfigPath?: string;
-}
-
-export interface CliContextOptions {
-    configDir?: string;
-    configCwd?: string;
-}
-
-export interface CliConfigContext {
-    configAdapter: FilesystemConfigAdapter;
-    stores: Record<string, any>;
-    settings: ReturnType<typeof getDefaultSettings>;
-    effectiveCwd: string;
-}
-
-export const createCliConfigAdapter = (configPath: string): FilesystemConfigAdapter => {
-    return new FilesystemConfigAdapter(configPath);
-};
-
-export const createCliAdapterFactory = (configAdapter: FilesystemConfigAdapter) => {
-    return (storeName: string) => {
-        const stores = configAdapter.stores!;
-        const storeEntry = stores[storeName];
-        if (!storeEntry) {
-            const available = Object.keys(stores).join(', ') || 'none';
-            throw new Error(
-                `Store '${storeName}' is not registered. Available stores: ${available}. ` +
-                    'Use --store to specify a registered store, or run `cortex store init` to create one.'
-            );
-        }
-
-        const storePath = storeEntry.properties?.path as string | undefined;
-        if (!storePath) {
-            throw new Error(
-                `Store '${storeName}' has no path configured. ` +
-                    'Check your cortex config or re-run `cortex store init`.'
-            );
-        }
-
-        return new FilesystemStorageAdapter(configAdapter, {
-            rootDirectory: storePath,
-        });
-    };
-};
-
-export const createCliConfigContext = async (
-    options: CliContextOptions = {}
-): Promise<Result<CliConfigContext, any>> => {
-    const envConfigPath = process.env.CORTEX_CONFIG;
-    const envConfigDir = process.env.CORTEX_CONFIG_DIR;
-    const envConfigCwd = process.env.CORTEX_CONFIG_CWD;
-
-    const explicitConfigPath =
-        typeof envConfigPath === 'string' && envConfigPath.length > 0
-            ? makeAbsolute(envConfigPath)
-            : undefined;
-
-    const dir = options.configDir ?? envConfigDir ?? resolve(homedir(), '.config', 'cortex');
-
-    const absoluteDir = makeAbsolute(dir);
-    const configPath = explicitConfigPath ?? resolve(absoluteDir, 'config.yaml');
-
-    const effectiveCwd =
-        options.configCwd ??
-        (typeof envConfigCwd === 'string' && envConfigCwd.length > 0
-            ? envConfigCwd
-            : process.cwd());
-
-    const configAdapter = createCliConfigAdapter(configPath);
-    const initResult = await configAdapter.initializeConfig();
-    if (!initResult.ok()) {
-        return initResult;
-    }
-
-    return ok({
-        configAdapter,
-        settings: configAdapter.settings!,
-        stores: configAdapter.stores!,
-        effectiveCwd,
-    });
-};
-
-/* Creates a CortexContext from the CLI environment, including loading configuration and setting up dependencies.
- * This function is used to create a context object that can be injected into command handlers for consistent access to the Cortex client and other utilities.
- */
-export const createCliCommandContext = async (
-    configDir?: string
-): Promise<Result<CortexContext, any>> => {
-    try {
-        const configContextResult = await createCliConfigContext({
-            configDir,
-        });
-        if (!configContextResult.ok()) {
-            return configContextResult;
-        }
-
-        const { configAdapter, settings, stores } = configContextResult.value;
-        const adapterFactory = createCliAdapterFactory(configAdapter);
-
-        const now = () => new Date();
-        const cortex = Cortex.init({
-            settings,
-            stores,
-            adapterFactory,
-        });
-
-        const logger = createCliLogger();
-
-        const context: CortexContext = {
-            config: configAdapter,
-            settings: settings ?? getDefaultSettings(),
-            stores: stores ?? {},
-            cortex,
-            now,
-            stdin,
-            stdout,
-            logger,
-        };
-
-        return ok(context);
-    } catch (error) {
-        return err({
-            code: 'CONTEXT_CREATION_FAILED',
-            message: `Unexpected error creating CLI command context: ${error instanceof Error ? error.message : String(error)}`,
-        });
-    }
-};

package/src/errors.spec.ts

@@ -1,264 +0,0 @@
-import { describe, expect, it } from 'bun:test';
-import { CommanderError, InvalidArgumentError } from '@commander-js/extra-typings';
-
-import { throwCliError, type CoreError } from './errors.ts';
-
-describe('throwCliError', () => {
-    describe('argument error codes', () => {
-        const argumentErrorCodes = [
-            'INVALID_PATH',
-            'INVALID_FILE_PATH',
-            'INVALID_SOURCE_PATH',
-            'INVALID_DESTINATION_PATH',
-            'INVALID_ARGUMENTS',
-            'INVALID_STORE_NAME',
-            'INVALID_STORE_PATH',
-            'MISSING_CONTENT',
-            'MULTIPLE_CONTENT_SOURCES',
-            'CONTENT_INPUT_FAILED',
-            'INVALID_COMMAND',
-            'GIT_REPO_REQUIRED',
-        ];
-
-        it.each(argumentErrorCodes)('should throw InvalidArgumentError for %s', (code) => {
-            const error: CoreError = {
-                code,
-                message: `Test message for ${code}`,
-            };
-
-            expect(() => throwCliError(error)).toThrow(InvalidArgumentError);
-        });
-
-        it('should preserve error message in InvalidArgumentError', () => {
-            const error: CoreError = {
-                code: 'INVALID_PATH',
-                message: 'Path must not be empty',
-            };
-
-            try {
-                throwCliError(error);
-                expect.unreachable('mapCoreError should have thrown');
-            }
-            catch (e) {
-                expect(e).toBeInstanceOf(InvalidArgumentError);
-                expect((e as InvalidArgumentError).message).toBe('Path must not be empty');
-            }
-        });
-
-        it('should handle empty message for argument errors', () => {
-            const error: CoreError = {
-                code: 'MISSING_CONTENT',
-                message: '',
-            };
-
-            try {
-                throwCliError(error);
-                expect.unreachable('mapCoreError should have thrown');
-            }
-            catch (e) {
-                expect(e).toBeInstanceOf(InvalidArgumentError);
-                expect((e as InvalidArgumentError).message).toBe('');
-            }
-        });
-    });
-
-    describe('non-argument error codes', () => {
-        const nonArgumentErrorCodes = [
-            'MEMORY_NOT_FOUND',
-            'STORE_NOT_FOUND',
-            'FILE_READ_FAILED',
-            'CATEGORY_NOT_FOUND',
-            'INTERNAL_ERROR',
-            'UNKNOWN_ERROR',
-            'SERIALIZE_FAILED',
-            'STORE_INIT_FAILED',
-            'STORE_REGISTRY_FAILED',
-            'STORE_ALREADY_EXISTS',
-            'STORAGE_ERROR',
-            'IO_READ_ERROR',
-            'IO_WRITE_ERROR',
-            'PARSE_FAILED',
-            'MOVE_FAILED',
-            'REMOVE_FAILED',
-            'REINDEX_FAILED',
-        ];
-
-        it.each(nonArgumentErrorCodes)('should throw CommanderError for %s', (code) => {
-            const error: CoreError = {
-                code,
-                message: `Test message for ${code}`,
-            };
-
-            expect(() => throwCliError(error)).toThrow(CommanderError);
-        });
-
-        it('should set exitCode to 1 for CommanderError', () => {
-            const error: CoreError = {
-                code: 'MEMORY_NOT_FOUND',
-                message: 'Memory not found at path',
-            };
-
-            try {
-                throwCliError(error);
-                expect.unreachable('mapCoreError should have thrown');
-            }
-            catch (e) {
-                expect(e).toBeInstanceOf(CommanderError);
-                expect((e as CommanderError).exitCode).toBe(1);
-            }
-        });
-
-        it('should preserve error code in CommanderError', () => {
-            const error: CoreError = {
-                code: 'STORE_NOT_FOUND',
-                message: 'Store not found',
-            };
-
-            try {
-                throwCliError(error);
-                expect.unreachable('mapCoreError should have thrown');
-            }
-            catch (e) {
-                expect(e).toBeInstanceOf(CommanderError);
-                expect((e as CommanderError).code).toBe('STORE_NOT_FOUND');
-            }
-        });
-
-        it('should preserve error message in CommanderError', () => {
-            const error: CoreError = {
-                code: 'FILE_READ_FAILED',
-                message: 'Could not read file: /path/to/file.txt',
-            };
-
-            try {
-                throwCliError(error);
-                expect.unreachable('mapCoreError should have thrown');
-            }
-            catch (e) {
-                expect(e).toBeInstanceOf(CommanderError);
-                expect((e as CommanderError).message).toBe(
-                    'Could not read file: /path/to/file.txt',
-                );
-            }
-        });
-
-        it('should handle empty message for non-argument errors', () => {
-            const error: CoreError = {
-                code: 'INTERNAL_ERROR',
-                message: '',
-            };
-
-            try {
-                throwCliError(error);
-                expect.unreachable('mapCoreError should have thrown');
-            }
-            catch (e) {
-                expect(e).toBeInstanceOf(CommanderError);
-                expect((e as CommanderError).message).toBe('');
-            }
-        });
-    });
-
-    describe('edge cases', () => {
-        it('should handle unknown error codes as non-argument errors', () => {
-            const error: CoreError = {
-                code: 'COMPLETELY_UNKNOWN_CODE',
-                message: 'An unexpected error',
-            };
-
-            try {
-                throwCliError(error);
-                expect.unreachable('mapCoreError should have thrown');
-            }
-            catch (e) {
-                expect(e).toBeInstanceOf(CommanderError);
-                expect((e as CommanderError).code).toBe('COMPLETELY_UNKNOWN_CODE');
-            }
-        });
-
-        it('should handle error codes that are similar to argument codes', () => {
-            const error: CoreError = {
-                code: 'INVALID_PATH_EXTRA', // Similar but not in the set
-                message: 'This should be a CommanderError',
-            };
-
-            try {
-                throwCliError(error);
-                expect.unreachable('mapCoreError should have thrown');
-            }
-            catch (e) {
-                expect(e).toBeInstanceOf(CommanderError);
-            }
-        });
-
-        it('should be case-sensitive for error codes', () => {
-            const error: CoreError = {
-                code: 'invalid_path', // lowercase version
-                message: 'This should be a CommanderError due to case sensitivity',
-            };
-
-            try {
-                throwCliError(error);
-                expect.unreachable('mapCoreError should have thrown');
-            }
-            catch (e) {
-                expect(e).toBeInstanceOf(CommanderError);
-            }
-        });
-
-        it('should handle message with special characters', () => {
-            const error: CoreError = {
-                code: 'INVALID_PATH',
-                message: 'Path contains invalid chars: <>&"\'\n\t',
-            };
-
-            try {
-                throwCliError(error);
-                expect.unreachable('mapCoreError should have thrown');
-            }
-            catch (e) {
-                expect(e).toBeInstanceOf(InvalidArgumentError);
-                expect((e as InvalidArgumentError).message).toBe(
-                    'Path contains invalid chars: <>&"\'\n\t',
-                );
-            }
-        });
-
-        it('should handle very long error messages', () => {
-            const longMessage = 'A'.repeat(10000);
-            const error: CoreError = {
-                code: 'MEMORY_NOT_FOUND',
-                message: longMessage,
-            };
-
-            try {
-                throwCliError(error);
-                expect.unreachable('mapCoreError should have thrown');
-            }
-            catch (e) {
-                expect(e).toBeInstanceOf(CommanderError);
-                expect((e as CommanderError).message).toBe(longMessage);
-            }
-        });
-    });
-
-    describe('return type verification', () => {
-        it('should never return (always throws)', () => {
-            const error: CoreError = {
-                code: 'INVALID_PATH',
-                message: 'Test',
-            };
-
-            let didReturn = false;
-            try {
-                throwCliError(error);
-                didReturn = true;
-            }
-            catch {
-                // Expected
-            }
-
-            expect(didReturn).toBe(false);
-        });
-    });
-});

package/src/errors.ts

@@ -1,105 +0,0 @@
-/**
- * Error mapping utilities for CLI commands.
- *
- * This module provides utilities to map core Result errors to Commander.js
- * exceptions. Commander.js uses specific exception types to control error
- * output and exit codes:
- *
- * - `InvalidArgumentError` - For user input validation errors (shows usage help)
- * - `CommanderError` - For other errors (shows error message only)
- *
- * @example
- * ```ts
- * const result = await runAddCommand(options);
- * if (!result.ok()) {
- *     mapCoreError(result.error);
- * }
- * ```
- */
-
-import { InvalidArgumentError, CommanderError } from '@commander-js/extra-typings';
-
-/**
- * Represents a core error with a code and message.
- *
- * This interface matches the error shape used throughout the CLI commands,
- * allowing consistent error handling across all command implementations.
- */
-export interface CoreError {
-    code: string;
-    message: string;
-    cause?: unknown;
-}
-
-/**
- * Error codes that indicate invalid user input or arguments.
- *
- * These errors result in `InvalidArgumentError` which causes Commander.js
- * to display usage help alongside the error message.
- *
- * Includes:
- * - Path validation errors (`INVALID_PATH`)
- * - Argument parsing errors (`INVALID_ARGUMENTS`)
- * - Store configuration errors (`INVALID_STORE_NAME`, `INVALID_STORE_PATH`)
- * - Content input errors (`MISSING_CONTENT`, `MULTIPLE_CONTENT_SOURCES`, `CONTENT_INPUT_FAILED`)
- * - Command syntax errors (`INVALID_COMMAND`)
- */
-const ARGUMENT_ERROR_CODES = new Set([
-    // Path validation
-    'INVALID_PATH',
-    'INVALID_FILE_PATH',
-    'INVALID_SOURCE_PATH',
-    'INVALID_DESTINATION_PATH',
-
-    // Argument parsing
-    'INVALID_ARGUMENTS',
-
-    // Store configuration
-    'INVALID_STORE_NAME',
-    'INVALID_STORE_PATH',
-
-    // Content input
-    'MISSING_CONTENT',
-    'MULTIPLE_CONTENT_SOURCES',
-    'CONTENT_INPUT_FAILED',
-
-    // Command syntax
-    'INVALID_COMMAND',
-
-    // Git detection (user needs to provide --name)
-    'GIT_REPO_REQUIRED',
-]);
-
-/**
- * Maps a core error to a Commander.js exception and throws it.
- *
- * This function examines the error code to determine the appropriate
- * Commander.js exception type:
- *
- * - **Argument errors** (`InvalidArgumentError`): For errors caused by invalid
- *   user input. Commander.js displays usage help for these errors.
- *
- * - **Other errors** (`CommanderError`): For system errors, missing resources,
- *   or internal failures. Commander.js displays only the error message.
- *
- * @param error - The core error to map
- * @throws {InvalidArgumentError} When the error code indicates invalid input
- * @throws {CommanderError} For all other error codes
- *
- * @example
- * ```ts
- * // In a command action handler
- * const result = await runShowCommand(options);
- * if (!result.ok()) {
- *     mapCoreError(result.error);
- *     // Never reaches here - mapCoreError always throws
- * }
- * ```
- */
-export function throwCliError(error: CoreError): never {
-    if (ARGUMENT_ERROR_CODES.has(error.code)) {
-        throw new InvalidArgumentError(error.message);
-    }
-
-    throw new CommanderError(1, error.code, error.message);
-}