@yeseh/cortex-cli 0.6.0

package/src/errors.spec.ts

@@ -0,0 +1,264 @@
+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

@@ -0,0 +1,105 @@
+/**
+ * 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);
+}

package/src/memory/commands/add.spec.ts

@@ -0,0 +1,169 @@
+/**
+ * Unit tests for the handleAdd command handler.
+ *
+ * @module cli/memory/commands/add.spec
+ */
+
+import { describe, it, expect, afterEach, beforeEach } from 'bun:test';
+import { CommanderError, InvalidArgumentError } from '@commander-js/extra-typings';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PassThrough } from 'node:stream';
+import {
+    ok,
+    type AdapterFactory,
+} from '@yeseh/cortex-core';
+import { handleAdd } from './add.ts';
+import {
+    createCaptureStream,
+    createMemoryCommandContext,
+    createMockMemoryCommandAdapter,
+} from './test-helpers.spec.ts';
+
+// ---------------------------------------------------------------------------
+// Local helpers
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('handleAdd', () => {
+    let tempDir: string;
+
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'cortex-add-'));
+    });
+
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+
+    it('should create a memory and write success message to stdout', async () => {
+        const capture = createCaptureStream();
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+            stdout: capture.stream,
+        });
+
+        await handleAdd(ctx, undefined, 'project/notes', { content: 'Hello world' });
+
+        const out = capture.getOutput();
+        expect(out).toContain('Added memory');
+        expect(out).toContain('project/notes');
+    });
+
+    it('should pass tags from options', async () => {
+        const capture = createCaptureStream();
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+            stdout: capture.stream,
+        });
+
+        await handleAdd(ctx, undefined, 'project/tagged', {
+            content: 'Tagged memory',
+            tags: ['foo', 'bar'],
+        });
+
+        expect(capture.getOutput()).toContain('Added memory');
+        expect(capture.getOutput()).toContain('project/tagged');
+    });
+
+    it('should pass expiresAt from options', async () => {
+        const capture = createCaptureStream();
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+            stdout: capture.stream,
+        });
+
+        await handleAdd(ctx, undefined, 'project/expiring', {
+            content: 'Expires soon',
+            expiresAt: '2030-12-31T00:00:00Z',
+        });
+
+        expect(capture.getOutput()).toContain('Added memory');
+    });
+
+    it('should pass citations from options', async () => {
+        const capture = createCaptureStream();
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+            stdout: capture.stream,
+        });
+
+        await handleAdd(ctx, undefined, 'project/cited', {
+            content: 'Cited memory',
+            citations: ['https://example.com/source'],
+        });
+
+        expect(capture.getOutput()).toContain('Added memory');
+    });
+
+    it('should throw CommanderError when store not found', async () => {
+        const failingFactory = (() => undefined) as unknown as AdapterFactory;
+
+        const stdin = new PassThrough();
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+            stdin,
+            adapterFactory: failingFactory,
+        });
+
+        await expect(
+            handleAdd(ctx, 'nonexistent', 'project/notes', { content: 'test' })
+        ).rejects.toThrow(CommanderError);
+    });
+
+    it('should throw InvalidArgumentError for MISSING_CONTENT when no content provided', async () => {
+        const stdin = new PassThrough();
+        stdin.end(); // EOF with no data → empty content → MISSING_CONTENT
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+            stdin,
+        });
+
+        await expect(handleAdd(ctx, undefined, 'project/notes', {})).rejects.toThrow(
+            InvalidArgumentError
+        );
+    });
+
+    it('should throw CommanderError when memory create fails due to missing category', async () => {
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter({
+                categories: {
+                    exists: async () => ok(false), // category absent → CATEGORY_NOT_FOUND
+                },
+            }),
+            storePath: tempDir,
+        });
+
+        await expect(
+            handleAdd(ctx, undefined, 'project/notes', { content: 'test' })
+        ).rejects.toThrow(CommanderError);
+    });
+
+    it('should use stdin when no content option is provided', async () => {
+        const stdin = new PassThrough();
+        stdin.end('Content from stdin');
+        const capture = createCaptureStream();
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+            stdin,
+            stdout: capture.stream,
+        });
+
+        await handleAdd(ctx, undefined, 'project/stdin', {});
+
+        const out = capture.getOutput();
+        expect(out).toContain('Added memory');
+        expect(out).toContain('stdin');
+    });
+});

package/src/memory/commands/add.ts

@@ -0,0 +1,157 @@
+/**
+ * Memory add command implementation using Commander.js.
+ *
+ * Creates a new memory at the specified path with content from inline text,
+ * a file, or stdin.
+ *
+ * @example
+ * ```bash
+ * # Add memory with inline content
+ * cortex memory add project/tech-stack --content "Using TypeScript and Node.js"
+ *
+ * # Add memory from a file
+ * cortex memory add project/notes --file ./notes.md
+ *
+ * # Add memory from stdin
+ * echo "My notes" | cortex memory add project/notes
+ *
+ * # Add memory with tags and expiration
+ * cortex memory add project/temp --content "Temporary note" \
+ *   --tags "temp,cleanup" --expires-at "2025-12-31T00:00:00Z"
+ * ```
+ */
+
+import { Command } from '@commander-js/extra-typings';
+import { throwCliError } from '../../errors.ts';
+import { type CortexContext } from '@yeseh/cortex-core';
+import { resolveInput as resolveCliContent } from '../../utils/input.ts';
+import { parseExpiresAt, parseTags } from '../parsing.ts';
+import { createCliCommandContext } from '../../context.ts';
+import { serializeOutput, type OutputFormat } from '../../output.ts';
+
+/** Options parsed by Commander for the add command */
+export interface AddCommandOptions {
+    content?: string;
+    file?: string;
+    tags?: string[];
+    expiresAt?: string;
+    citations?: string[];
+    format?: string;
+}
+/**
+ * Handler for the memory add command.
+ * Exported for direct testing without Commander parsing.
+ *
+ * @param path - Memory path (e.g., "project/tech-stack")
+ * @param options - Command options from Commander
+ * @param storeName - Optional store name from parent command
+ * @param deps - Injectable dependencies for testing
+ */
+export async function handleAdd(
+    ctx: CortexContext,
+    storeName: string | undefined,
+    path: string,
+    options: AddCommandOptions
+): Promise<void> {
+    const content = await resolveCliContent({
+        content: options.content,
+        filePath: options.file,
+        stream: ctx.stdin,
+        // `memory add` accepts stdin by default (when piped).
+        stdinRequested: options.content === undefined && options.file === undefined,
+    });
+
+    if (!content.ok()) {
+        throwCliError(content.error);
+    }
+
+    if (!content.value.content) {
+        throwCliError({
+            code: 'MISSING_CONTENT',
+            message: 'Memory content is required via --content, --file, or stdin.',
+        });
+    }
+
+    const { content: memoryContent, source } = content.value;
+    const tags = parseTags(options.tags);
+    const expiresAt = parseExpiresAt(options.expiresAt);
+    const citations = options.citations ?? [];
+
+    const storeResult = ctx.cortex.getStore(storeName ?? 'global');
+    if (!storeResult.ok()) {
+        throwCliError(storeResult.error);
+    }
+
+    const store = storeResult.value;
+    const timestamp = ctx.now() ?? new Date();
+    const memoryClient = store.getMemory(path);
+    const memoryResult = await memoryClient.create({
+        content: memoryContent!,
+        metadata: {
+            tags,
+            source,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            expiresAt,
+            citations,
+        },
+    });
+
+    if (!memoryResult.ok()) {
+        throwCliError(memoryResult.error);
+    }
+
+    const memory = memoryResult.value;
+    const out = ctx.stdout ?? process.stdout;
+
+    const rawFormat = options.format;
+    if (!rawFormat) {
+        out.write(`Added memory ${memory.path} (${source}).\n`);
+    } else {
+        const format = rawFormat as OutputFormat;
+        const serialized = serializeOutput(
+            {
+                kind: 'memory',
+                value: {
+                    path: memory.path.toString(),
+                    metadata: memory.metadata,
+                    content: memory.content,
+                },
+            },
+            format
+        );
+        if (!serialized.ok()) {
+            throwCliError({ code: 'SERIALIZE_FAILED', message: serialized.error.message });
+        }
+        out.write(serialized.value + '\n');
+    }
+}
+
+/**
+ * The `memory add` subcommand.
+ *
+ * Creates a new memory at the specified path. Content can be provided via:
+ * - `--content` flag for inline text
+ * - `--file` flag to read from a file
+ * - stdin when piped
+ *
+ * The `--store` option is inherited from the parent `memory` command.
+ */
+export const addCommand = new Command('add')
+    .description('Create a new memory')
+    .argument('<path>', 'Memory path (e.g., project/tech-stack)')
+    .option('-c, --content <text>', 'Memory content as inline text')
+    .option('-f, --file <filepath>', 'Read content from a file')
+    .option('-t, --tags <value...>', 'Tags (can be repeated or comma-separated)')
+    .option('-e, --expires-at <date>', 'Expiration date (ISO 8601)')
+    .option('--citation <value...>', 'Citation references (file paths or URLs)')
+    .option('-o, --format <format>', 'Output format (yaml, json, toon)')
+    .action(async (path, options, command) => {
+        const parentOpts = command.parent?.opts() as { store?: string } | undefined;
+        const context = await createCliCommandContext();
+        if (!context.ok()) {
+            throwCliError(context.error);
+        }
+
+        await handleAdd(context.value, parentOpts?.store, path, options);
+    });