@yeseh/cortex-cli 0.6.0

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

@@ -0,0 +1,80 @@
+/**
+ * Unit tests for memory command definitions.
+ *
+ * Verifies that memory subcommands expose the expected names,
+ * arguments, and options.
+ *
+ * @module cli/memory/commands/definitions.spec
+ */
+
+import { describe, expect, it } from 'bun:test';
+
+import { listCommand } from './list.ts';
+import { moveCommand } from './move.ts';
+import { removeCommand } from './remove.ts';
+import { showCommand } from './show.ts';
+import { updateCommand } from './update.ts';
+
+const getLongOptions = (command: { options: ReadonlyArray<{ long?: string }> }): string[] =>
+    command.options.map((option) => option.long ?? '').filter(Boolean);
+
+describe('memory command definitions', () => {
+    describe('listCommand', () => {
+        it('should expose expected command name and usage', () => {
+            expect(listCommand.name()).toBe('list');
+            expect(listCommand.usage()).toContain('[category]');
+        });
+
+        it('should register expected options', () => {
+            const options = getLongOptions(listCommand);
+            expect(options).toContain('--store');
+            expect(options).toContain('--include-expired');
+            expect(options).toContain('--format');
+        });
+    });
+
+    describe('moveCommand', () => {
+        it('should expose expected command name and usage', () => {
+            expect(moveCommand.name()).toBe('move');
+            expect(moveCommand.usage()).toContain('<from>');
+            expect(moveCommand.usage()).toContain('<to>');
+        });
+    });
+
+    describe('removeCommand', () => {
+        it('should expose expected command name and usage', () => {
+            expect(removeCommand.name()).toBe('remove');
+            expect(removeCommand.usage()).toContain('<path>');
+        });
+    });
+
+    describe('showCommand', () => {
+        it('should expose expected command name and usage', () => {
+            expect(showCommand.name()).toBe('show');
+            expect(showCommand.usage()).toContain('<path>');
+        });
+
+        it('should register expected options', () => {
+            const options = getLongOptions(showCommand);
+            expect(options).toContain('--include-expired');
+            expect(options).toContain('--format');
+        });
+    });
+
+    describe('updateCommand', () => {
+        it('should expose expected command name and usage', () => {
+            expect(updateCommand.name()).toBe('update');
+            expect(updateCommand.usage()).toContain('<path>');
+        });
+
+        it('should register expected options', () => {
+            const options = getLongOptions(updateCommand);
+            expect(options).toContain('--content');
+            expect(options).toContain('--file');
+            expect(options).toContain('--tags');
+            expect(options).toContain('--expires-at');
+            expect(options).toContain('--no-expires-at');
+            expect(options).toContain('--citation');
+        });
+    });
+});

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

@@ -0,0 +1,123 @@
+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 {
+    CategoryPath,
+    MemoryPath,
+    ok,
+    type AdapterFactory,
+    type Category,
+} from '@yeseh/cortex-core';
+
+import { handleList } from './list.ts';
+import {
+    createCaptureStream,
+    createMemoryCommandContext,
+    createMemoryFixture,
+    createMockMemoryCommandAdapter,
+} from './test-helpers.spec.ts';
+
+describe('handleList', () => {
+    let tempDir: string;
+
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'cortex-cli-memory-list-'));
+    });
+
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+
+    it('should throw InvalidArgumentError for invalid category paths', async () => {
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+        });
+
+        await expect(handleList(ctx, undefined, '/ /', { format: 'yaml' })).rejects.toThrow(
+            InvalidArgumentError,
+        );
+    });
+
+    it('should throw CommanderError when the adapter factory returns nothing', async () => {
+        const nullFactory = (() => undefined) as unknown as AdapterFactory;
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+            adapterFactory: nullFactory,
+            stores: {
+                global: {
+                    kind: 'filesystem',
+                    properties: { path: tempDir },
+                    categories: {},
+                },
+            },
+        });
+
+        await expect(handleList(ctx, 'missing-store', undefined, {})).rejects.toThrow(
+            CommanderError,
+        );
+    });
+
+    it('should write serialized list output', async () => {
+        const memoryPath = MemoryPath.fromString('project/one');
+        if (!memoryPath.ok()) {
+            throw new Error('Test setup failed to create memory path.');
+        }
+        const memory = createMemoryFixture('project/one');
+
+        const rootCategory: Category = {
+            memories: [],
+            subcategories: [
+                {
+                    path: CategoryPath.fromString('project').unwrap(),
+                    memoryCount: 1,
+                    description: 'Project memories',
+                },
+            ],
+        };
+
+        const projectCategory: Category = {
+            memories: [
+                {
+                    path: memoryPath.value,
+                    tokenEstimate: 42,
+                },
+            ],
+            subcategories: [],
+        };
+
+        const adapter = createMockMemoryCommandAdapter({
+            indexes: {
+                load: async (path: CategoryPath) => {
+                    if (path.isRoot) {
+                        return ok(rootCategory);
+                    }
+                    if (path.toString() === 'project') {
+                        return ok(projectCategory);
+                    }
+                    return ok(null);
+                },
+            },
+            memories: {
+                load: async () => ok(memory),
+            },
+        });
+
+        const capture = createCaptureStream();
+        const ctx = createMemoryCommandContext({
+            adapter,
+            storePath: tempDir,
+            stdout: capture.stream,
+        });
+
+        await handleList(ctx, undefined, undefined, { format: 'json' });
+
+        const output = JSON.parse(capture.getOutput());
+        expect(output.memories).toHaveLength(1);
+        expect(output.memories[0].path).toBe('project/one');
+        expect(output.subcategories[0].path).toBe('project');
+    });
+});

package/src/memory/commands/list.ts

@@ -0,0 +1,268 @@
+/**
+ * Memory list command for browsing memories with optional filtering.
+ *
+ * Lists all memories in a category, or all memories across all categories
+ * if no category is specified. Expired memories are excluded by default
+ * unless the `--include-expired` flag is provided.
+ *
+ * When no category is specified, the command dynamically discovers all
+ * root categories from the store's index rather than using a hardcoded list.
+ *
+ * @example
+ * ```bash
+ * # List all memories
+ * cortex memory list
+ *
+ * # List memories in a specific category
+ * cortex memory list project/cortex
+ *
+ * # Include expired memories
+ * cortex memory list --include-expired
+ *
+ * # Output in JSON format
+ * cortex memory list --format json
+ *
+ * # Use a specific store (either placement works)
+ * cortex memory list -s my-store
+ * cortex memory -s my-store list
+ * ```
+ */
+
+import { Command } from '@commander-js/extra-typings';
+import { throwCliError } from '../../errors.ts';
+
+import { CategoryPath, type CategoryClient } from '@yeseh/cortex-core/category';
+import { serialize, type CortexContext } from '@yeseh/cortex-core';
+import type { SubcategoryEntry } from '@yeseh/cortex-core/category';
+import { type OutputFormat } from '../../output.ts';
+import { createCliCommandContext } from '../../context.ts';
+
+/**
+ * Options for the list command.
+ */
+export interface ListCommandOptions {
+    /** Include expired memories in the output */
+    includeExpired?: boolean;
+    /** Output format (yaml, json, toon) */
+    format?: string;
+    /** Store name (can be specified on subcommand or parent) */
+    store?: string;
+}
+
+/**
+ * Dependencies for the list command handler.
+ * Allows injection for testing.
+ */
+export interface ListHandlerDeps {
+    /** Output stream for writing results (defaults to process.stdout) */
+    stdout?: NodeJS.WritableStream;
+    /** Current time for expiration checks */
+    now?: Date;
+}
+
+/**
+ * Entry representing a memory in the list output.
+ */
+export interface ListMemoryEntry {
+    path: string;
+    tokenEstimate: number;
+    summary?: string;
+    expiresAt?: Date;
+    isExpired: boolean;
+}
+
+/**
+ * Entry representing a subcategory in the list output.
+ */
+export interface ListSubcategoryEntry {
+    path: string;
+    memoryCount: number;
+    description?: string;
+}
+
+/**
+ * Result of the list command containing memories and subcategories.
+ */
+export interface ListResult {
+    memories: ListMemoryEntry[];
+    subcategories: ListSubcategoryEntry[];
+}
+
+/**
+ * Handles the list command execution.
+ *
+ * This function:
+ * 1. Resolves the store context
+ * 2. Loads category index (or all categories if none specified)
+ * 3. Collects memories and subcategories, filtering expired if needed
+ * 4. Formats and outputs the result
+ *
+ * @param category - Optional category path to list (lists all if omitted)
+ * @param options - Command options (includeExpired, format)
+ * @param storeName - Optional store name from parent command
+ * @param deps - Optional dependencies for testing
+ * @throws {InvalidArgumentError} When arguments are invalid
+ * @throws {CommanderError} When read or parse fails
+ */
+export async function handleList(
+    ctx: CortexContext,
+    storeName: string | undefined,
+    category: string | undefined,
+    options: ListCommandOptions,
+    deps: ListHandlerDeps = {}
+): Promise<void> {
+    const categoryResult = CategoryPath.fromString(category ?? '');
+    if (!categoryResult.ok()) {
+        throwCliError(categoryResult.error);
+    }
+
+    const storeResult = ctx.cortex.getStore(storeName ?? 'global');
+    if (!storeResult.ok()) {
+        throwCliError(storeResult.error);
+    }
+
+    const rootResult = storeResult.value.root();
+    if (!rootResult.ok()) {
+        throwCliError(rootResult.error);
+    }
+
+    const root = rootResult.value;
+    let categoryClient: CategoryClient;
+
+    if (categoryResult.value.isRoot) {
+        categoryClient = root;
+    } else {
+        const categoryClientResult = root.getCategory(categoryResult.value.toString());
+        if (!categoryClientResult.ok()) {
+            throwCliError(categoryClientResult.error);
+        }
+
+        categoryClient = categoryClientResult.value;
+    }
+    const now = deps.now ?? ctx.now();
+    const includeExpired = options.includeExpired ?? false;
+    const visited = new Set<string>();
+
+    const collectMemories = async (client: CategoryClient): Promise<ListMemoryEntry[]> => {
+        const categoryKey = client.rawPath;
+        if (visited.has(categoryKey)) {
+            return [];
+        }
+        visited.add(categoryKey);
+
+        const memoriesResult = await client.listMemories({ includeExpired });
+        if (!memoriesResult.ok()) {
+            throwCliError(memoriesResult.error);
+        }
+
+        const memories: ListMemoryEntry[] = [];
+        for (const entry of memoriesResult.value) {
+            const memoryClient = client.getMemory(entry.path.slug.toString());
+            const memoryResult = await memoryClient.get({ includeExpired: true, now });
+            if (!memoryResult.ok()) {
+                if (memoryResult.error.code === 'MEMORY_NOT_FOUND') {
+                    continue;
+                }
+                if (!includeExpired && memoryResult.error.code === 'MEMORY_EXPIRED') {
+                    continue;
+                }
+                throwCliError(memoryResult.error);
+            }
+
+            const memory = memoryResult.value;
+            const isExpired = memory.isExpired(now);
+            if (!includeExpired && isExpired) {
+                continue;
+            }
+
+            memories.push({
+                path: entry.path.toString(),
+                tokenEstimate: entry.tokenEstimate,
+                summary: undefined,
+                expiresAt: memory.metadata.expiresAt,
+                isExpired,
+            });
+        }
+
+        const subcategoriesResult = await client.listSubcategories();
+        if (!subcategoriesResult.ok()) {
+            throwCliError(subcategoriesResult.error);
+        }
+
+        for (const subcategory of subcategoriesResult.value) {
+            const subcategoryClientResult = root.getCategory(subcategory.path.toString());
+            if (!subcategoryClientResult.ok()) {
+                throwCliError(subcategoryClientResult.error);
+            }
+            const subMemories = await collectMemories(subcategoryClientResult.value);
+            memories.push(...subMemories);
+        }
+
+        return memories;
+    };
+
+    const subcategoriesResult = await categoryClient.listSubcategories();
+    if (!subcategoriesResult.ok()) {
+        throwCliError(subcategoriesResult.error);
+    }
+
+    const memories = await collectMemories(categoryClient);
+    const result: ListResult = {
+        memories,
+        subcategories: subcategoriesResult.value.map((subcategory: SubcategoryEntry) => ({
+            path: subcategory.path.toString(),
+            memoryCount: subcategory.memoryCount,
+            description: subcategory.description,
+        })),
+    };
+
+    // 3. Format and output
+    const validFormats = ['yaml', 'json', 'toon'] as const;
+    const format: OutputFormat = validFormats.includes(options.format as OutputFormat)
+        ? (options.format as OutputFormat)
+        : 'yaml';
+    const output = serialize(result, format);
+    if (!output.ok()) {
+        throwCliError({ code: 'SERIALIZE_FAILED', message: output.error.message });
+    }
+
+    const out = deps.stdout ?? ctx.stdout;
+    out.write(output.value + '\n');
+}
+
+/**
+ * The `list` subcommand for browsing memories.
+ *
+ * Lists memories in a category, or all memories across all root categories
+ * if no category is specified. By default, expired memories are excluded.
+ *
+ * The `--store` option can be specified either on this command or on the
+ * parent `memory` command for flexibility.
+ *
+ * @example
+ * ```bash
+ * cortex memory list
+ * cortex memory list project/cortex
+ * cortex memory list --include-expired
+ * cortex memory list --format json
+ * cortex memory list -s my-store
+ * cortex memory -s my-store list
+ * ```
+ */
+export const listCommand = new Command('list')
+    .description('List memories in a category')
+    .argument('[category]', 'Category path to list (lists all if omitted)')
+    .option('-s, --store <name>', 'Use a specific named store')
+    .option('-x, --include-expired', 'Include expired memories')
+    .option('-o, --format <format>', 'Output format (yaml, json, toon)', 'yaml')
+    .action(async (category, options, command) => {
+        const parentOpts = command.parent?.opts() as { store?: string } | undefined;
+        // Allow store to be specified on either the subcommand or parent command
+        const storeName = options.store ?? parentOpts?.store;
+        const context = await createCliCommandContext();
+        if (!context.ok()) {
+            throwCliError(context.error);
+        }
+
+        await handleList(context.value, storeName, category, options);
+    });

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

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

package/src/memory/commands/move.ts

@@ -0,0 +1,115 @@
+/**
+ * Memory move command implementation using Commander.js.
+ *
+ * Moves a memory from one path to another within the same store.
+ *
+ * @example
+ * ```bash
+ * # Move a memory to a new location
+ * cortex memory move project/old-name project/new-name
+ *
+ * # Move with explicit store
+ * cortex memory --store my-store move project/old project/new
+ * ```\n */
+
+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 move command. */
+export interface MoveCommandOptions {
+    /** Output format (yaml, json, toon) */
+    format?: string;
+}
+
+/**
+ * Handler for the memory move 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 from - Source memory path
+ * @param to - Destination memory path
+ */
+export async function handleMove(
+    ctx: CortexContext,
+    storeName: string | undefined,
+    from: string,
+    to: string,
+    options: MoveCommandOptions = {}
+): Promise<void> {
+    const fromResult = MemoryPath.fromString(from);
+    if (!fromResult.ok()) {
+        throwCliError(fromResult.error);
+    }
+
+    const toResult = MemoryPath.fromString(to);
+    if (!toResult.ok()) {
+        throwCliError(toResult.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 sourceCategoryResult = fromResult.value.category.isRoot
+        ? rootResult
+        : rootResult.value.getCategory(fromResult.value.category.toString());
+    if (!sourceCategoryResult.ok()) {
+        throwCliError(sourceCategoryResult.error);
+    }
+
+    const sourceMemory = sourceCategoryResult.value.getMemory(fromResult.value.slug.toString());
+    const moveResult = await sourceMemory.move(toResult.value);
+    if (!moveResult.ok()) {
+        throwCliError(moveResult.error);
+    }
+
+    const out = ctx.stdout ?? process.stdout;
+    const rawFormat = options.format;
+    if (!rawFormat) {
+        out.write(`Moved memory ${fromResult.value.toString()} to ${toResult.value.toString()}.\n`);
+    } else {
+        const format = rawFormat as OutputFormat;
+        const serialized = serializeOutput(
+            { kind: 'moved-memory', value: { from: fromResult.value.toString(), to: toResult.value.toString() } },
+            format
+        );
+        if (!serialized.ok()) {
+            throwCliError({ code: 'SERIALIZE_FAILED', message: serialized.error.message });
+        }
+        out.write(serialized.value + '\n');
+    }
+}
+
+/**
+ * The `memory move` subcommand.
+ *
+ * Moves a memory from one path to another within the store.
+ * Both paths must be valid memory slug paths.
+ *
+ * The `--store` option is inherited from the parent `memory` command.
+ */
+export const moveCommand = new Command('move')
+    .description('Move a memory to a new path')
+    .argument('<from>', 'Source memory path')
+    .argument('<to>', 'Destination memory path')
+    .option('-o, --format <format>', 'Output format (yaml, json, toon)')
+    .action(async (from, to, options, command) => {
+        const parentOpts = command.parent?.opts() as { store?: string } | undefined;
+        const context = await createCliCommandContext();
+        if (!context.ok()) {
+            throwCliError(context.error);
+        }
+
+        await handleMove(context.value, parentOpts?.store, from, to, options);
+    });