@yeseh/cortex-cli 0.6.8 → 0.6.10

package/src/output.ts

@@ -1,119 +0,0 @@
-/**
- * Output format types and serialization helpers.
- *
- * This module provides type definitions for CLI output payloads and a thin
- * wrapper around the core serialize function. Validation is expected to happen
- * at object construction time, not during serialization.
- */
-
-import { err, ok, type Result } from '@yeseh/cortex-core';
-import { serialize, type OutputFormat } from '@yeseh/cortex-core';
-
-// Re-export OutputFormat from core
-export type { OutputFormat };
-
-export interface OutputMemoryMetadata {
-    createdAt: Date;
-    updatedAt?: Date;
-    tags: string[];
-    source?: string;
-    tokenEstimate?: number;
-    expiresAt?: Date;
-}
-
-export interface OutputPath {
-    path: string;
-}
-
-export interface OutputMemory {
-    path: string;
-    metadata: OutputMemoryMetadata;
-    content: string;
-}
-export interface OutputMovedMemory {
-    from: string;
-    to: string;
-}
-
-export interface OutputCategoryMemory {
-    path: string;
-    tokenEstimate?: number;
-    summary?: string;
-}
-
-export interface OutputSubcategory {
-    path: string;
-    memoryCount: number;
-}
-
-export interface OutputCategory {
-    path: string;
-    memories: OutputCategoryMemory[];
-    subcategories: OutputSubcategory[];
-}
-
-export interface OutputCreatedCategory {
-    path: string;
-    created: boolean;
-}
-
-export interface OutputStore {
-    name: string;
-    path: string;
-}
-
-export interface OutputStoreRegistry {
-    stores: OutputStore[];
-}
-
-export interface OutputStoreInit {
-    path: string;
-    name: string;
-}
-
-export interface OutputInit {
-    path: string;
-    categories: string[];
-}
-
-export type OutputPayload =
-    | { kind: 'memory'; value: OutputMemory }
-    | { kind: 'moved-memory'; value: OutputMovedMemory }
-    | { kind: 'path'; value: OutputPath }
-    | { kind: 'category'; value: OutputCategory }
-    | { kind: 'created-category'; value: OutputCreatedCategory}
-    | { kind: 'store'; value: OutputStore }
-    | { kind: 'store-registry'; value: OutputStoreRegistry }
-    | { kind: 'store-init'; value: OutputStoreInit }
-    | { kind: 'init'; value: OutputInit };
-
-export interface OutputSerializeError {
-    code: 'INVALID_FORMAT' | 'SERIALIZE_FAILED';
-    message: string;
-}
-
-/**
- * Serialize an output payload to the specified format.
- *
- * This is a thin wrapper around the core serialize function that extracts
- * the value from the discriminated union and handles errors.
- *
- * @param payload - The output payload to serialize
- * @param format - The output format ('yaml', 'json', or 'toon')
- * @returns Result with serialized string or error
- */
-export const serializeOutput = (
-    payload: OutputPayload,
-    format: OutputFormat,
-): Result<string, OutputSerializeError> => {
-    const result = serialize(payload, format);
-
-    if (result.ok()) {
-        return ok(result.value);
-    }
-
-    return err({
-        code: result.error.code === 'INVALID_FORMAT' ? 'INVALID_FORMAT' : 'SERIALIZE_FAILED',
-        message: result.error.message,
-    });
-};

package/src/program.spec.ts

@@ -1,46 +0,0 @@
-/**
- * Unit tests for the Commander.js program setup and runProgram entrypoint.
- *
- * Verifies that the program is correctly wired with the expected name,
- * version, and top-level subcommands, and that `runProgram` is exported
- * as a callable function.
- *
- * @module cli/program.spec
- */
-
-import { describe, it, expect } from 'bun:test';
-import { program, runProgram } from './program.ts';
-import packageInfo from '../package.json'
-
-describe('program', () => {
-    it('should have name "cortex"', () => {
-        expect(program.name()).toBe('cortex');
-    });
-
-    it(`should have version "${packageInfo.version}"`, () => {
-        expect(program.version()).toBe(packageInfo.version);
-    });
-
-    it('should have "memory" command registered', () => {
-        const names = program.commands.map((c) => c.name());
-        expect(names).toContain('memory');
-    });
-
-    it('should have "store" command registered', () => {
-        const names = program.commands.map((c) => c.name());
-        expect(names).toContain('store');
-    });
-
-    it('should have "init" command registered', () => {
-        const names = program.commands.map((c) => c.name());
-        expect(names).toContain('init');
-    });
-});
-
-describe('runProgram', () => {
-    it('should be a function', () => {
-        // Do NOT call runProgram() — it would parse process.argv and trigger
-        // real command execution. We only verify it is exported correctly.
-        expect(typeof runProgram).toBe('function');
-    });
-});

package/src/program.ts

@@ -1,75 +0,0 @@
-/**
- * Commander.js program setup for Cortex CLI.
- *
- * This module sets up the main Commander program and wires together
- * all command groups. It serves as the entry point for the CLI.
- *
- * @module cli/program
- */
-
-import { Command } from '@commander-js/extra-typings';
-
-import { memoryCommand } from './memory/index.ts';
-import { storeCommand } from './store/index.ts';
-import { initCommand } from './commands/init.ts';
-import { categoryCommand } from './category/index.ts';
-import { createCliLogger } from './observability.ts';
-import packageInfo from '../package.json'
-
-/**
- * The main Commander program instance for Cortex CLI.
- *
- * Configured with:
- * - Name: cortex
- * - Description: Memory system for AI agents
- * - Version: 0.1.0
- *
- * @example
- * ```ts
- * import { program } from './program.ts';
- * await program.parseAsync(process.argv);
- * ```
- */
-const program = new Command()
-    .name('cortex')
-    .description('Memory system for AI agents')
-    .version(packageInfo.version);
-
-program.addCommand(memoryCommand);
-program.addCommand(categoryCommand);
-program.addCommand(storeCommand);
-program.addCommand(initCommand);
-
-export { program };
-
-/**
- * Runs the CLI program by parsing command-line arguments.
- *
- * This function handles errors gracefully and sets the appropriate
- * exit code on failure.
- *
- * @returns A promise that resolves when the program completes
- *
- * @example
- * ```ts
- * import { runProgram } from './program.ts';
- * await runProgram();
- * ```
- */
-export const runProgram = async (): Promise<void> => {
-    try {
-        await program.parseAsync(process.argv);
-    }
-    catch (error) {
-        // Commander.js handles most errors by writing to stderr and exiting.
-        // This catch handles any unexpected errors that slip through.
-        const logger = createCliLogger();
-        if (error instanceof Error) {
-            logger.error(error.message);
-        }
-        else {
-            logger.error('An unexpected error occurred');
-        }
-        process.exitCode = 1;
-    }
-};

package/src/run.spec.ts

@@ -1,31 +0,0 @@
-/**
- * Unit tests for the run.ts CLI entrypoint.
- *
- * `run.ts` is a side-effect-only module that calls `runProgram()` on import.
- * Because importing it would immediately parse `process.argv`, we do NOT
- * import it directly in tests. Instead we verify that the function it
- * delegates to (`runProgram`) is correctly exported from `program.ts`.
- *
- * @module cli/run.spec
- */
-
-import { describe, it, expect } from 'bun:test';
-
-import { runProgram } from './program.ts';
-
-describe('run module', () => {
-    it('should delegate to runProgram from program.ts', () => {
-        // run.ts calls runProgram() — verify the delegated function is callable
-        expect(typeof runProgram).toBe('function');
-    });
-
-    it('runProgram should return a Promise', () => {
-        // Verify the return type without actually executing
-        // (calling it would parse process.argv)
-        const returnType = runProgram.constructor.name;
-        // AsyncFunction or Function — both are acceptable
-        expect([
-            'Function', 'AsyncFunction',
-        ]).toContain(returnType);
-    });
-});

package/src/run.ts

@@ -1,9 +0,0 @@
-#!/usr/bin/env bun
-/**
- * CLI runner script for integration testing.
- * This script is spawned as a subprocess by the integration tests.
- */
-
-import { runProgram } from './program.ts';
-
-runProgram();

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

@@ -1,131 +0,0 @@
-/**
- * Unit tests for the store add command handler.
- *
- * Note: `handleAdd` reads and writes the global config file via `Bun.file()` and
- * `Bun.write()`. These I/O calls are not dependency-injected, so the success
- * path is not testable at the unit level without filesystem mocking (prohibited
- * by project rules). Only the validation paths that throw before any I/O are
- * covered here.
- *
- * Slug normalization behavior: `Slug.from()` normalizes most inputs rather than
- * rejecting them (e.g. 'INVALID' → 'invalid', 'my store' → 'my-store'). Only
- * empty/whitespace strings fail `Slug.from()` and produce `InvalidArgumentError`.
- *
- * @module cli/store/commands/add.spec
- */
-
-import { describe, it } from 'bun:test';
-import { handleAdd } from './add.ts';
-import {
-    createMockContext,
-    expectInvalidArgumentError,
-    expectCommanderError,
-} from '../../test-helpers.spec.ts';
-
-describe('handleAdd', () => {
-    describe('store name validation', () => {
-        it('should throw InvalidArgumentError for an empty store name', async () => {
-            const { ctx } = createMockContext({ stores: {} });
-
-            await expectInvalidArgumentError(
-                () => handleAdd(ctx, '', '/some/path'),
-                'Store name must be a lowercase slug',
-            );
-        });
-
-        it('should throw InvalidArgumentError for a whitespace-only store name', async () => {
-            const { ctx } = createMockContext({ stores: {} });
-
-            await expectInvalidArgumentError(
-                () => handleAdd(ctx, '   ', '/some/path'),
-                'Store name must be a lowercase slug',
-            );
-        });
-    });
-
-    describe('store path validation', () => {
-        it('should throw InvalidArgumentError for an empty store path', async () => {
-            const { ctx } = createMockContext({ stores: {} });
-
-            await expectInvalidArgumentError(
-                () => handleAdd(ctx, 'valid-name', ''),
-                'Store path is required',
-            );
-        });
-
-        it('should throw InvalidArgumentError for a whitespace-only store path', async () => {
-            const { ctx } = createMockContext({ stores: {} });
-
-            await expectInvalidArgumentError(
-                () => handleAdd(ctx, 'valid-name', '   '),
-                'Store path is required',
-            );
-        });
-    });
-
-    describe('store already exists check', () => {
-        it('should throw CommanderError when the store name already exists in context', async () => {
-            // 'global' is pre-registered in the mock context
-            const { ctx } = createMockContext({
-                stores: {
-                    global: {
-                        kind: 'filesystem',
-                        categoryMode: 'free',
-                        categories: {},
-                        properties: { path: '/existing/path' },
-                    },
-                },
-            });
-
-            await expectCommanderError(
-                () => handleAdd(ctx, 'global', '/new/path'),
-                'STORE_ALREADY_EXISTS',
-                'already registered',
-            );
-        });
-
-        it('should throw CommanderError with store name in the error message', async () => {
-            const { ctx } = createMockContext({
-                stores: {
-                    'my-store': {
-                        kind: 'filesystem',
-                        categoryMode: 'free',
-                        categories: {},
-                        properties: { path: '/some/path' },
-                    },
-                },
-            });
-
-            await expectCommanderError(
-                () => handleAdd(ctx, 'my-store', '/new/path'),
-                'STORE_ALREADY_EXISTS',
-                'my-store',
-            );
-        });
-
-        it('should normalize the store name before checking for existence', async () => {
-            // Slug.from('MY-STORE') → 'my-store', so 'MY-STORE' matches 'my-store'
-            const { ctx } = createMockContext({
-                stores: {
-                    'my-store': {
-                        kind: 'filesystem',
-                        categoryMode: 'free',
-                        categories: {},
-                        properties: { path: '/some/path' },
-                    },
-                },
-            });
-
-            await expectCommanderError(
-                () => handleAdd(ctx, 'MY-STORE', '/new/path'),
-                'STORE_ALREADY_EXISTS',
-            );
-        });
-    });
-
-    // NOTE: The success path (steps 4–6) requires reading and writing the global
-    // config file via Bun.file() / Bun.write(). These calls use the hardcoded
-    // getDefaultConfigPath() with no injection point, so they cannot be tested
-    // at the unit level without filesystem mocking (which is prohibited).
-    // The success path should be covered by integration tests.
-});

package/src/store/commands/add.ts

@@ -1,231 +0,0 @@
-/**
- * Store add command for registering a new store.
- *
- * This command registers a new store in the global registry with a given
- * name and filesystem path. Paths are resolved relative to the current
- * working directory, with support for tilde expansion.
- *
- * @example
- * ```bash
- * # Register a store with an absolute path
- * cortex store add work /path/to/work/memories
- *
- * # Register a store with a relative path
- * cortex store add project ./cortex
- *
- * # Register a store with tilde expansion
- * cortex store add personal ~/memories
- * ```
- */
-
-import { mkdir } from 'node:fs/promises';
-import { dirname } from 'node:path';
-import { Command } from '@commander-js/extra-typings';
-import { throwCliError } from '../../errors.ts';
-import { getDefaultConfigPath } from '../../utils/paths.ts';
-import { serializeOutput, type OutputStore, type OutputFormat } from '../../output.ts';
-import { resolveUserPath } from '../../utils/paths.ts';
-import { Slug, parseConfig, type CortexContext, type ConfigStore } from '@yeseh/cortex-core';
-import { createCliCommandContext } from '../../context.ts';
-
-/**
- * Options for the add command.
- */
-export interface AddCommandOptions {
-    /** Output format (yaml, json, toon) */
-    format?: string;
-}
-
-/**
- * Dependencies for the add command handler.
- * Allows injection for testing.
- */
-export interface AddHandlerDeps {
-    /** Output stream for writing results (defaults to process.stdout) */
-    stdout?: NodeJS.WritableStream;
-}
-
-/**
- * Validates store name input.
- *
- * @param name - The raw store name input
- * @returns The validated, trimmed store name
- * @throws {InvalidArgumentError} When the store name is empty or invalid
- */
-function validateStoreName(name: string): string {
-    const slugResult = Slug.from(name);
-    if (!slugResult.ok()) {
-        throwCliError({
-            code: 'INVALID_STORE_NAME',
-            message: 'Store name must be a lowercase slug (letters, numbers, hyphens).',
-        });
-    }
-
-    return slugResult.value.toString();
-}
-
-/**
- * Validates and resolves store path input.
- *
- * @param storePath - The raw store path input
- * @param cwd - The current working directory for relative path resolution
- * @returns The resolved absolute path
- * @throws {InvalidArgumentError} When the store path is empty
- */
-function validateAndResolvePath(storePath: string, cwd: string): string {
-    const trimmed = storePath.trim();
-    if (!trimmed) {
-        throwCliError({ code: 'INVALID_STORE_PATH', message: 'Store path is required.' });
-    }
-    return resolveUserPath(trimmed, cwd);
-}
-
-/**
- * Writes the serialized output to the output stream.
- *
- * @param output - The store output payload
- * @param format - The output format
- * @param stdout - The output stream
- */
-function writeOutput(
-    output: OutputStore,
-    format: OutputFormat,
-    stdout: NodeJS.WritableStream,
-): void {
-    const serialized = serializeOutput({ kind: 'store', value: output }, format);
-    if (!serialized.ok()) {
-        throwCliError({ code: 'SERIALIZE_FAILED', message: serialized.error.message });
-    }
-    stdout.write(serialized.value + '\n');
-}
-
-/**
- * Handles the add command execution.
- *
- * This function:
- * 1. Validates the store name format
- * 2. Validates and resolves the store path
- * 3. Checks if store already exists in context
- * 4. Reads current config file
- * 5. Adds the store to the config and saves
- * 6. Outputs the result
- *
- * @param ctx - The CortexContext with loaded configuration
- * @param name - The store name to register
- * @param storePath - The filesystem path to the store
- * @param options - Command options (format)
- * @param deps - Optional dependencies for testing
- * @throws {InvalidArgumentError} When the store name or path is invalid
- * @throws {CommanderError} When the store already exists or config operations fail
- */
-export async function handleAdd(
-    ctx: CortexContext,
-    name: string,
-    storePath: string,
-    options: AddCommandOptions = {},
-    deps: AddHandlerDeps = {},
-): Promise<void> {
-    const cwd = ctx.cwd ?? process.cwd();
-    const stdout = deps.stdout ?? ctx.stdout ?? process.stdout;
-    const configPath = getDefaultConfigPath();
-
-    // 1. Validate inputs
-    const trimmedName = validateStoreName(name);
-    const resolvedPath = validateAndResolvePath(storePath, cwd);
-
-    // 2. Check if store already exists in context
-    if (ctx.stores[trimmedName]) {
-        throwCliError({
-            code: 'STORE_ALREADY_EXISTS',
-            message: `Store '${trimmedName}' is already registered.`,
-        });
-    }
-
-    // 3. Read current config file (or start with empty config if it doesn't exist)
-    const configFile = Bun.file(configPath);
-    let parsedConfig: { settings?: unknown; stores: Record<string, unknown> };
-
-    if (await configFile.exists()) {
-        let configContents: string;
-        try {
-            configContents = await configFile.text();
-        }
-        catch {
-            throwCliError({
-                code: 'CONFIG_READ_FAILED',
-                message: `Failed to read config at ${configPath}`,
-            });
-        }
-
-        const parsed = parseConfig(configContents!);
-        if (!parsed.ok()) {
-            throwCliError(parsed.error);
-        }
-        parsedConfig = parsed.value;
-    }
-    else {
-        // Config doesn't exist yet — start with empty config
-        parsedConfig = { settings: undefined, stores: {} };
-        // Ensure config directory exists
-        await mkdir(dirname(configPath), { recursive: true });
-    }
-
-    // 4. Add new store to config
-    const newStore: ConfigStore = {
-        kind: 'filesystem',
-        categoryMode: 'free',
-        categories: {},
-        properties: { path: resolvedPath },
-    };
-
-    const updatedConfig = {
-        ...parsedConfig,
-        stores: {
-            ...parsedConfig.stores,
-            [trimmedName]: newStore,
-        },
-    };
-
-    // 5. Write updated config
-    const serialized = Bun.YAML.stringify(updatedConfig, null, 2);
-    try {
-        await Bun.write(configPath, serialized);
-    }
-    catch {
-        throwCliError({
-            code: 'CONFIG_WRITE_FAILED',
-            message: `Failed to write config at ${configPath}`,
-        });
-    }
-
-    // 6. Output result
-    const output: OutputStore = { name: trimmedName, path: resolvedPath };
-    const format: OutputFormat = (options.format as OutputFormat) ?? 'yaml';
-    writeOutput(output, format, stdout);
-}
-
-/**
- * The `add` subcommand for registering a new store.
- *
- * Registers a store with the given name and filesystem path. The path is
- * resolved relative to the current working directory, with support for
- * tilde expansion.
- *
- * @example
- * ```bash
- * cortex store add work /path/to/work/memories
- * cortex store add project ./cortex --format json
- * ```
- */
-export const addCommand = new Command('add')
-    .description('Register a new store')
-    .argument('<name>', 'Store name (lowercase slug)')
-    .argument('<path>', 'Filesystem path to the store')
-    .option('-o, --format <format>', 'Output format (yaml, json, toon)', 'yaml')
-    .action(async (name, path, options) => {
-        const context = await createCliCommandContext();
-        if (!context.ok()) {
-            throwCliError(context.error);
-        }
-        await handleAdd(context.value, name, path, options);
-    });