@yeseh/cortex-cli 0.6.0

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

@@ -0,0 +1,79 @@
+import { afterEach, beforeEach, describe, expect, it } 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 { MemoryPath, ok } from '@yeseh/cortex-core';
+
+import { handleRemove } from './remove.ts';
+import {
+    createCaptureStream,
+    createMemoryCommandContext,
+    createMemoryFixture,
+    createMockMemoryCommandAdapter,
+} from './test-helpers.spec.ts';
+
+describe('handleRemove', () => {
+    let tempDir: string;
+
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'cortex-cli-memory-remove-'));
+    });
+
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+
+    it('should throw InvalidArgumentError for invalid memory paths', async () => {
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+        });
+
+        await expect(handleRemove(ctx, undefined, 'invalid')).rejects.toThrow(
+            InvalidArgumentError,
+        );
+    });
+
+    it('should throw CommanderError when store is missing', async () => {
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+            stores: undefined,
+        });
+
+        await expect(handleRemove(ctx, 'missing-store', 'project/one')).rejects.toThrow(
+            CommanderError,
+        );
+    });
+
+    it('should remove memory and report output', async () => {
+        const memory = createMemoryFixture('project/remove');
+        const removeCalls: MemoryPath[] = [];
+
+        const adapter = createMockMemoryCommandAdapter({
+            memories: {
+                load: async () => ok(memory),
+                remove: async (path: MemoryPath) => {
+                    removeCalls.push(path);
+                    return ok(undefined);
+                },
+            },
+        });
+
+        const capture = createCaptureStream();
+        const ctx = createMemoryCommandContext({
+            adapter,
+            storePath: tempDir,
+            stdout: capture.stream,
+        });
+
+        await handleRemove(ctx, undefined, 'project/remove');
+
+        expect(removeCalls).toHaveLength(1);
+        if (removeCalls[0]) {
+            expect(removeCalls[0].toString()).toBe('project/remove');
+        }
+        expect(capture.getOutput()).toContain('Removed memory project/remove.');
+    });
+});

package/src/memory/commands/remove.ts

@@ -0,0 +1,104 @@
+/**
+ * Memory remove command implementation using Commander.js.
+ *
+ * Deletes an existing memory at the specified path.
+ *
+ * @example
+ * ```bash
+ * # Remove a memory
+ * cortex memory remove project/tech-stack
+ *
+ * # Remove memory from a specific store
+ * cortex memory --store work remove project/notes
+ * ```
+ */
+
+import { Command } from '@commander-js/extra-typings';
+import { throwCliError } from '../../errors.ts';
+import { MemoryPath, type CortexContext } from '@yeseh/cortex-core';
+import { createCliCommandContext } from '../../context.ts';
+import { serializeOutput, type OutputFormat } from '../../output.ts';
+
+/** Options for the remove command. */
+export interface RemoveCommandOptions {
+    /** Output format (yaml, json, toon) */
+    format?: string;
+}
+
+/**
+ * Handler for the memory remove command.
+ * Exported for direct testing without Commander parsing.
+ *
+ * @param ctx - CLI context containing Cortex client and streams
+ * @param storeName - Optional store name from parent command
+ * @param path - Memory path to remove (e.g., "project/tech-stack")
+ */
+export async function handleRemove(
+    ctx: CortexContext,
+    storeName: string | undefined,
+    path: string,
+    options: RemoveCommandOptions = {}
+): Promise<void> {
+    const pathResult = MemoryPath.fromString(path);
+    if (!pathResult.ok()) {
+        throwCliError(pathResult.error);
+    }
+
+    const storeResult = ctx.cortex.getStore(storeName ?? 'global');
+    if (!storeResult.ok()) {
+        throwCliError(storeResult.error);
+    }
+
+    const store = storeResult.value;
+    const rootResult = store.root();
+    if (!rootResult.ok()) {
+        throwCliError(rootResult.error);
+    }
+
+    const categoryResult = pathResult.value.category.isRoot
+        ? rootResult
+        : rootResult.value.getCategory(pathResult.value.category.toString());
+    if (!categoryResult.ok()) {
+        throwCliError(categoryResult.error);
+    }
+
+    const memoryClient = categoryResult.value.getMemory(pathResult.value.slug.toString());
+    const removeResult = await memoryClient.delete();
+    if (!removeResult.ok()) {
+        throwCliError(removeResult.error);
+    }
+
+    const out = ctx.stdout ?? process.stdout;
+    const rawFormat = options.format;
+    if (!rawFormat) {
+        out.write(`Removed memory ${pathResult.value.toString()}.\n`);
+    } else {
+        const format = rawFormat as OutputFormat;
+        const serialized = serializeOutput({kind: 'path', value: { path: pathResult.value.toString() }}, format);
+        if (!serialized.ok()) {
+            throwCliError({ code: 'SERIALIZE_FAILED', message: serialized.error.message });
+        }
+        out.write(serialized.value + '\n');
+    }
+}
+
+/**
+ * The `memory remove` subcommand.
+ *
+ * Deletes an existing memory at the specified path.
+ *
+ * The `--store` option is inherited from the parent `memory` command.
+ */
+export const removeCommand = new Command('remove')
+    .description('Delete a memory')
+    .argument('<path>', 'Memory path to remove')
+    .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 handleRemove(context.value, parentOpts?.store, path, options);
+    });

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

@@ -0,0 +1,71 @@
+import { afterEach, beforeEach, describe, expect, it } 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 { ok } from '@yeseh/cortex-core';
+
+import { handleShow } from './show.ts';
+import {
+    createCaptureStream,
+    createMemoryCommandContext,
+    createMemoryFixture,
+    createMockMemoryCommandAdapter,
+} from './test-helpers.spec.ts';
+
+describe('handleShow', () => {
+    let tempDir: string;
+
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'cortex-cli-memory-show-'));
+    });
+
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+
+    it('should throw InvalidArgumentError for invalid memory paths', async () => {
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+        });
+
+        await expect(handleShow(ctx, undefined, 'invalid', { format: 'yaml' })).rejects.toThrow(
+            InvalidArgumentError,
+        );
+    });
+
+    it('should throw CommanderError when store is missing', async () => {
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+            stores: undefined,
+        });
+
+        await expect(handleShow(ctx, 'missing-store', 'project/one', { format: 'yaml' })).rejects.toThrow(
+            CommanderError,
+        );
+    });
+
+    it('should output serialized memory details', async () => {
+        const memory = createMemoryFixture('project/show', {}, 'Show content');
+        const adapter = createMockMemoryCommandAdapter({
+            memories: {
+                load: async () => ok(memory),
+            },
+        });
+        const capture = createCaptureStream();
+        const ctx = createMemoryCommandContext({
+            adapter,
+            storePath: tempDir,
+            stdout: capture.stream,
+        });
+
+        await handleShow(ctx, undefined, 'project/show', { format: 'json' });
+
+        const output = JSON.parse(capture.getOutput());
+        expect(output.value.path).toBe('project/show');
+        expect(output.value.content).toBe('Show content');
+        expect(output.value.metadata.tags).toEqual(['test']);
+    });
+});

package/src/memory/commands/show.ts

@@ -0,0 +1,164 @@
+/**
+ * Memory show command for displaying a memory's content and metadata.
+ *
+ * This command reads a memory from the store and displays it in the
+ * specified format. Expired memories are excluded by default unless
+ * the `--include-expired` flag is provided.
+ *
+ * @example
+ * ```bash
+ * # Show a memory in YAML format (default)
+ * cortex memory show project/notes
+ *
+ * # Show a memory in JSON format
+ * cortex memory show project/notes --format json
+ *
+ * # Include expired memories
+ * cortex memory show project/notes --include-expired
+ *
+ * # Use a specific store
+ * cortex memory --store my-store show project/notes
+ * ```
+ */
+
+import { Command } from '@commander-js/extra-typings';
+import { throwCliError } from '../../errors.ts';
+
+import { defaultTokenizer, MemoryPath, type CortexContext } from '@yeseh/cortex-core';
+import { type StoreClient } from '@yeseh/cortex-core/store';
+import { serializeOutput, type OutputMemory, type OutputFormat } from '../../output.ts';
+import { createCliCommandContext } from '../../context.ts';
+
+/**
+ * Options for the show command.
+ */
+export interface ShowCommandOptions {
+    /** Include expired memories in the output */
+    includeExpired?: boolean;
+    /** Output format (yaml, json, toon) */
+    format?: string;
+}
+
+/**
+ * Dependencies for the show command handler.
+ * Allows injection for testing.
+ */
+export interface ShowHandlerDeps {
+    /** Output stream for writing results (defaults to process.stdout) */
+    stdout?: NodeJS.WritableStream;
+    /** Pre-resolved store client for testing */
+    store?: StoreClient;
+}
+
+/**
+ * Handles the show command execution.
+ *
+ * This function:
+ * 1. Resolves the store context
+ * 2. Validates the memory path
+ * 3. Reads the memory file from storage
+ * 4. Parses the memory content and frontmatter
+ * 5. Checks expiration status (unless --include-expired)
+ * 6. Serializes and outputs the result
+ *
+ * @param path - The memory path to show (e.g., "project/notes")
+ * @param options - Command options (includeExpired, format)
+ * @param storeName - Optional store name from parent command
+ * @param deps - Optional dependencies for testing
+ * @throws {InvalidArgumentError} When the path is invalid
+ * @throws {CommanderError} When the memory is not found or read fails
+ */
+export async function handleShow(
+    ctx: CortexContext,
+    storeName: string | undefined,
+    path: string,
+    options: ShowCommandOptions,
+    deps: ShowHandlerDeps = {}
+): Promise<void> {
+    const pathResult = MemoryPath.fromString(path);
+    if (!pathResult.ok()) {
+        throwCliError(pathResult.error);
+    }
+
+    const storeResult = ctx.cortex.getStore(storeName ?? 'global');
+    if (!storeResult.ok()) {
+        throwCliError(storeResult.error);
+    }
+
+    const store = deps.store ?? storeResult.value;
+
+    const rootResult = store.root();
+    if (!rootResult.ok()) {
+        throwCliError(rootResult.error);
+    }
+
+    const categoryResult = pathResult.value.category.isRoot
+        ? rootResult
+        : rootResult.value.getCategory(pathResult.value.category.toString());
+    if (!categoryResult.ok()) {
+        throwCliError(categoryResult.error);
+    }
+
+    const memoryClient = categoryResult.value.getMemory(pathResult.value.slug.toString());
+    const readResult = await memoryClient.get({
+        includeExpired: options.includeExpired ?? false,
+        now: ctx.now(),
+    });
+    if (!readResult.ok()) {
+        throwCliError(readResult.error);
+    }
+
+    const memory = readResult.value;
+    const tokenEstimateResult = defaultTokenizer.estimateTokens(memory.content);
+    const tokenEstimate = tokenEstimateResult.ok() ? tokenEstimateResult.value : undefined;
+
+    const outputMemory: OutputMemory = {
+        path: memory.path.toString(),
+        metadata: {
+            createdAt: memory.metadata.createdAt,
+            updatedAt: memory.metadata.updatedAt,
+            tags: memory.metadata.tags,
+            source: memory.metadata.source,
+            tokenEstimate,
+            expiresAt: memory.metadata.expiresAt,
+        },
+        content: memory.content,
+    };
+
+    const format = (options.format as OutputFormat) ?? 'yaml';
+    const serialized = serializeOutput({kind: 'memory', value: outputMemory}, format);
+    if (!serialized.ok()) {
+        throwCliError({ code: 'SERIALIZE_FAILED', message: serialized.error.message });
+    }
+
+    const out = deps.stdout ?? ctx.stdout;
+    out.write(serialized.value + '\n');
+}
+
+/**
+ * The `show` subcommand for displaying a memory.
+ *
+ * Reads a memory from the store and displays its content and metadata
+ * in the specified format. By default, expired memories are excluded.
+ *
+ * @example
+ * ```bash
+ * cortex memory show project/notes
+ * cortex memory show project/notes --format json
+ * cortex memory show project/notes --include-expired
+ * ```
+ */
+export const showCommand = new Command('show')
+    .description('Display a memory')
+    .argument('<path>', 'Memory path to show')
+    .option('-x, --include-expired', 'Include expired memories')
+    .option('-o, --format <format>', 'Output format (yaml, json, toon)', 'yaml')
+    .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 handleShow(context.value, parentOpts?.store, path, options);
+    });

package/src/memory/commands/test-helpers.spec.ts

@@ -0,0 +1,127 @@
+import { PassThrough } from 'node:stream';
+import {
+    Cortex,
+    Memory,
+    ok,
+    type AdapterFactory,
+    type ConfigAdapter,
+    type ConfigStores,
+    type CortexContext,
+    type CortexSettings,
+    type MemoryMetadata,
+    type StorageAdapter,
+} from '@yeseh/cortex-core';
+
+export const createMockMemoryCommandAdapter = (
+    overrides: Record<string, unknown> = {},
+): StorageAdapter =>
+    ({
+        memories: {
+            load: async () => ok(null),
+            save: async () => ok(undefined),
+            add: async () => ok(undefined),
+            remove: async () => ok(undefined),
+            move: async () => ok(undefined),
+            ...(overrides.memories as object | undefined),
+        },
+        indexes: {
+            load: async () => ok(null),
+            write: async () => ok(undefined),
+            reindex: async () => ok({ warnings: [] }),
+            updateAfterMemoryWrite: async () => ok(undefined),
+            ...(overrides.indexes as object | undefined),
+        },
+        categories: {
+            exists: async () => ok(true),
+            ensure: async () => ok(undefined),
+            delete: async () => ok(undefined),
+            setDescription: async () => ok(undefined),
+            ...(overrides.categories as object | undefined),
+        },
+    }) as unknown as StorageAdapter;
+
+export const createMemoryCommandContext = (options: {
+    adapter: StorageAdapter;
+    storePath: string;
+    stdout?: PassThrough;
+    stdin?: PassThrough;
+    stores?: ConfigStores;
+    settings?: CortexSettings;
+    now?: () => Date;
+    adapterFactory?: AdapterFactory;
+}): CortexContext => {
+    const stores: ConfigStores = options.stores ?? {
+        global: {
+            kind: 'filesystem',
+            properties: { path: options.storePath },
+            categories: {},
+        },
+    };
+
+    const cortex = Cortex.init({
+        settings: options.settings,
+        stores,
+        adapterFactory: options.adapterFactory ?? (() => options.adapter),
+    });
+
+    return {
+        cortex,
+        config: {
+            path: '/tmp/test/config.yaml',
+            data: null,
+            get stores() {
+                return stores;
+            },
+            get settings() {
+                return options.settings ?? null;
+            },
+            initializeConfig: async () => ok(undefined),
+            getSettings: async () => ok(options.settings ?? {}),
+            getStores: async () => ok(stores),
+            getStore: async (name: string) => ok(stores[name] ?? null),
+            saveStore: async () => ok(undefined),
+        } as ConfigAdapter,
+        settings: (options.settings ?? {}) as CortexSettings,
+        stores,
+        now: options.now ?? (() => new Date('2025-01-01T00:00:00.000Z')),
+        stdin: (options.stdin ?? new PassThrough()) as unknown as NodeJS.ReadStream,
+        stdout: (options.stdout ?? new PassThrough()) as unknown as NodeJS.WriteStream,
+    };
+};
+
+export const createCaptureStream = (): { stream: PassThrough; getOutput: () => string } => {
+    let output = '';
+    const stream = new PassThrough();
+    const originalWrite = stream.write.bind(stream);
+    stream.write = ((chunk: unknown, encoding?: unknown, cb?: unknown) => {
+        output += Buffer.from(chunk as Buffer).toString(
+            typeof encoding === 'string' ? (encoding as BufferEncoding) : undefined,
+        );
+        return originalWrite(chunk as Buffer, encoding as BufferEncoding, cb as () => void);
+    }) as typeof stream.write;
+
+    return { stream, getOutput: () => output };
+};
+
+export const createMemoryFixture = (
+    path: string,
+    overrides: Partial<MemoryMetadata> = {},
+    content = 'Memory content',
+): Memory => {
+    const timestamp = new Date('2025-01-01T00:00:00.000Z');
+    const metadata: MemoryMetadata = {
+        createdAt: timestamp,
+        updatedAt: timestamp,
+        tags: ['test'],
+        source: 'user',
+        citations: [],
+        ...overrides,
+    };
+
+    const result = Memory.init(path, metadata, content);
+    if (!result.ok()) {
+        throw new Error('Test setup failed to create memory.');
+    }
+
+    return result.value;
+};

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

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, describe, expect, it } 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 { Memory, MemoryPath, ok } from '@yeseh/cortex-core';
+
+import { handleUpdate } from './update.ts';
+import {
+    createCaptureStream,
+    createMemoryCommandContext,
+    createMemoryFixture,
+    createMockMemoryCommandAdapter,
+} from './test-helpers.spec.ts';
+
+describe('handleUpdate', () => {
+    let tempDir: string;
+
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'cortex-cli-memory-update-'));
+    });
+
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+
+    it('should throw InvalidArgumentError for invalid memory paths', async () => {
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+        });
+
+        await expect(handleUpdate(ctx, undefined, 'invalid', { content: 'Next' })).rejects.toThrow(
+            InvalidArgumentError,
+        );
+    });
+
+    it('should throw CommanderError when store is missing', async () => {
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+            stores: undefined,
+        });
+
+        await expect(
+            handleUpdate(ctx, 'missing-store', 'project/one', { content: 'Next' }),
+        ).rejects.toThrow(CommanderError);
+    });
+
+    it('should update memory and report output', async () => {
+        const memory = createMemoryFixture('project/update', {}, 'Original content');
+        const writeCalls: Memory[] = [];
+
+        const adapter = createMockMemoryCommandAdapter({
+            memories: {
+                load: async () => ok(memory),
+                save: async (_: MemoryPath, next: Memory) => {
+                    writeCalls.push(next);
+                    return ok(undefined);
+                },
+            },
+            indexes: {
+                updateAfterMemoryWrite: async () => ok(undefined),
+            },
+        });
+
+        const capture = createCaptureStream();
+        const ctx = createMemoryCommandContext({
+            adapter,
+            storePath: tempDir,
+            stdout: capture.stream,
+        });
+
+        await handleUpdate(ctx, undefined, 'project/update', {
+            content: 'Updated content',
+            tags: ['new-tag'],
+        });
+
+        expect(writeCalls).toHaveLength(1);
+        if (writeCalls[0]) {
+            expect(writeCalls[0].content).toBe('Updated content');
+            expect(writeCalls[0].metadata.tags).toEqual(['new-tag']);
+        }
+        expect(capture.getOutput()).toContain('Updated memory project/update.');
+    });
+});