@yeseh/cortex-cli 0.6.0

package/src/category/commands/create.spec.ts

@@ -0,0 +1,139 @@
+/**
+ * Unit tests for the handleCreate command handler.
+ *
+ * @module cli/category/commands/create.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 { err, ok } from '@yeseh/cortex-core';
+import { type AdapterFactory } from '@yeseh/cortex-core';
+
+import { handleCreate } from './create.ts';
+import {
+    createCaptureStream,
+    createMemoryCommandContext,
+    createMockMemoryCommandAdapter,
+} from '../../memory/commands/test-helpers.spec.ts';
+
+describe('handleCreate', () => {
+    let tempDir: string;
+
+    beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'cortex-category-create-'));
+    });
+
+    afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+
+    it('should write "Created <path>" to stdout when category is new', async () => {
+        const capture = createCaptureStream();
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter({
+                categories: {
+                    exists: async () => ok(false),
+                    ensure: async () => ok(undefined),
+                },
+            }),
+            storePath: tempDir,
+            stdout: capture.stream,
+        });
+
+        await handleCreate(ctx, undefined, 'standards/typescript');
+
+        const output = capture.getOutput();
+        expect(output).toContain('Created');
+        expect(output).toContain('standards/typescript');
+    });
+
+    it('should write already exists message when category exists', async () => {
+        const capture = createCaptureStream();
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter({
+                categories: {
+                    exists: async () => ok(true),
+                },
+            }),
+            storePath: tempDir,
+            stdout: capture.stream,
+        });
+
+        await handleCreate(ctx, undefined, 'standards/typescript');
+
+        const output = capture.getOutput();
+        expect(output).toContain('Category already exists');
+        expect(output).toContain('standards/typescript');
+    });
+
+    it('should serialize as JSON when --format json is passed', async () => {
+        const capture = createCaptureStream();
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter({
+                categories: {
+                    exists: async () => ok(false),
+                    ensure: async () => ok(undefined),
+                },
+            }),
+            storePath: tempDir,
+            stdout: capture.stream,
+        });
+
+        await handleCreate(ctx, undefined, 'standards', { format: 'json' });
+
+        const parsed = JSON.parse(capture.getOutput());
+        expect(parsed.value.path).toBe('standards');
+        expect(parsed.value.created).toBeTrue();
+    });
+
+    it('should throw CommanderError when store not found', async () => {
+        const failingFactory = (() => undefined) as unknown as AdapterFactory;
+
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter(),
+            storePath: tempDir,
+            adapterFactory: failingFactory,
+        });
+
+        await expect(handleCreate(ctx, 'nonexistent', 'standards')).rejects.toThrow(CommanderError);
+    });
+
+    it('should throw InvalidArgumentError for INVALID_PATH errors', async () => {
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter({
+                categories: {
+                    exists: async () => ok(false),
+                    ensure: async () => err({
+                        code: 'INVALID_PATH',
+                        message: 'Invalid category path: /',
+                    }),
+                },
+            }),
+            storePath: tempDir,
+        });
+
+        await expect(handleCreate(ctx, undefined, 'standards')).rejects.toThrow(InvalidArgumentError);
+    });
+
+    it('should throw CommanderError when storage ensure fails', async () => {
+        const ctx = createMemoryCommandContext({
+            adapter: createMockMemoryCommandAdapter({
+                categories: {
+                    exists: async () => ok(false),
+                    ensure: async () => err({
+                        code: 'WRITE_FAILED',
+                        message: 'Failed to write category index.',
+                    }),
+                },
+            }),
+            storePath: tempDir,
+        });
+
+        await expect(handleCreate(ctx, undefined, 'standards/typescript')).rejects.toThrow(
+            CommanderError,
+        );
+    });
+});

package/src/category/commands/create.ts

@@ -0,0 +1,115 @@
+/**
+ * Category create command.
+ *
+ * Creates a category at the specified path, including any missing ancestors.
+ *
+ * @example
+ * ```bash
+ * # Create a category in default store
+ * cortex category create standards/typescript
+ *
+ * # Create a category in a specific store
+ * cortex category --store my-store create standards/typescript
+ *
+ * # Serialize output as JSON
+ * cortex category create standards --format json
+ * ```
+ */
+
+import { Command } from '@commander-js/extra-typings';
+import { type CortexContext, type Result } from '@yeseh/cortex-core';
+
+import { createCliCommandContext } from '../../context.ts';
+import { throwCliError } from '../../errors.ts';
+import { serializeOutput, type OutputFormat } from '../../output.ts';
+
+/** Options parsed by Commander for the create command */
+export interface CreateCommandOptions {
+    description?: string;
+    format?: string;
+}
+
+/**
+ * Writes command output to stdout.
+ *
+ * @param payload - Category creation result payload
+ * @param options - Command options
+ * @param stdout - Output stream
+ */
+function writeCreateOutput(
+    payload: { path: string; created: boolean },
+    options: CreateCommandOptions,
+    stdout: NodeJS.WritableStream,
+): void {
+    const rawFormat = options.format;
+
+    if (!rawFormat) {
+        const verb = payload.created ? 'Created' : 'Category already exists:';
+        stdout.write(`${verb} ${payload.path}\n`);
+        return;
+    }
+
+    const serialized = serializeOutput({ kind: 'created-category', value: payload }, rawFormat as OutputFormat);
+    if (!serialized.ok()) {
+        throwCliError({ code: 'SERIALIZE_FAILED', message: serialized.error.message });
+    }
+    stdout.write(serialized.value + '\n');
+}
+
+/**
+ * Unwrap a Result and throw a mapped CLI error on failure.
+ *
+ * @param result - Result value
+ * @returns Unwrapped value
+ */
+function unwrapOrThrow<T, E extends { code: string; message: string }>(result: Result<T, E>): T {
+    if (!result.ok()) {
+        throwCliError(result.error);
+    }
+
+    return result.value;
+}
+
+/**
+ * Handler for the category create command.
+ * Exported for direct testing without Commander parsing.
+ *
+ * @param ctx - CLI execution context
+ * @param storeName - Optional store name from parent command
+ * @param path - Category path (e.g., "standards/typescript")
+ * @param options - Command options from Commander
+ */
+export async function handleCreate(
+    ctx: CortexContext,
+    storeName: string | undefined,
+    path: string,
+    options: CreateCommandOptions = {}
+): Promise<void> {
+    const store = unwrapOrThrow(ctx.cortex.getStore(storeName ?? 'global'));
+    const root = unwrapOrThrow(store.root());
+    const category = unwrapOrThrow(root.getCategory(path));
+    const result = unwrapOrThrow(await category.create());
+
+    const out = ctx.stdout ?? process.stdout;
+    writeCreateOutput(result, options, out);
+}
+
+/**
+ * The `category create` subcommand.
+ *
+ * Creates a category and any missing ancestors.
+ */
+export const createCommand = new Command('create')
+    .description('Create a category (and any missing ancestors)')
+    .argument('<path>', 'Category path (e.g., standards/typescript)')
+    .option('-d, --description <text>', 'Optional description for the category')
+    .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 handleCreate(context.value, parentOpts?.store, path, options);
+    });

package/src/category/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Category command group for the CLI.
+ *
+ * This module defines the `category` command group, which provides operations
+ * for managing categories in the Cortex memory system. The `--store` option
+ * is defined at the group level and inherited by all subcommands.
+ */
+
+import { Command } from '@commander-js/extra-typings';
+
+import { createCommand } from './commands/create';
+
+/**
+ * The `category` command group.
+ *
+ * Provides category management operations. The `--store` option allows
+ * targeting a specific named store instead of the default store.
+ * This option is inherited by all subcommands.
+ */
+export const categoryCommand = new Command('category')
+    .description('Category operations')
+    .option('-s, --store <name>', 'Use a specific named store');
+
+categoryCommand.addCommand(createCommand);

package/src/commands/init.spec.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it, mock } from 'bun:test';
+import { CommanderError } from '@commander-js/extra-typings';
+import { PassThrough } from 'node:stream';
+import { err, ok, type ConfigStore, type CortexContext } from '@yeseh/cortex-core';
+
+import { handleInit } from './init.ts';
+import type { PromptDeps } from '../utils/prompts.ts';
+
+const existingGlobalStore: ConfigStore = {
+    kind: 'filesystem',
+    categoryMode: 'free',
+    categories: {},
+    properties: { path: '/tmp/existing-global-store' },
+};
+
+const createContext = (config: CortexContext['config']): { ctx: CortexContext; stdout: PassThrough } => {
+    const stdout = new PassThrough();
+    let output = '';
+
+    stdout.on('data', (chunk: Buffer | string) => {
+        output += chunk.toString();
+    });
+
+    const ctx = {
+        cortex: {} as CortexContext['cortex'],
+        config,
+        settings: {},
+        stores: {},
+        now: () => new Date('2025-01-01T00:00:00.000Z'),
+        stdin: new PassThrough() as unknown as NodeJS.ReadStream,
+        stdout: stdout as unknown as NodeJS.WriteStream,
+    } as CortexContext;
+
+    return {
+        ctx,
+        stdout: Object.assign(stdout, {
+            getOutput: () => output,
+        }) as PassThrough,
+    };
+};
+
+describe('handleInit', () => {
+    it('should initialize config and create global store when missing', async () => {
+        const initializeConfig = mock(async () => ok(undefined));
+        const getStore = mock(async () => ok(null));
+        const saveStore = mock(async () => ok(undefined));
+
+        const { ctx, stdout } = createContext({
+            path: '/tmp/test-config.yaml',
+            data: null,
+            stores: null,
+            settings: null,
+            initializeConfig,
+            getSettings: async () => ok({}),
+            getStores: async () => ok({}),
+            getStore,
+            saveStore,
+        });
+
+        await handleInit(ctx, { format: 'json' });
+
+        expect(initializeConfig).toHaveBeenCalledTimes(1);
+        expect(saveStore).toHaveBeenCalledTimes(1);
+
+        const output = (stdout as PassThrough & { getOutput: () => string }).getOutput();
+        const parsed = JSON.parse(output) as { value: { path: string } };
+        expect(parsed.value.path).toContain('/.config/cortex/memory');
+    });
+
+    it('should throw when global store already exists without force', async () => {
+        const saveStore = mock(async () => ok(undefined));
+
+        const { ctx } = createContext({
+            path: '/tmp/test-config.yaml',
+            data: null,
+            stores: null,
+            settings: null,
+            initializeConfig: async () => ok(undefined),
+            getSettings: async () => ok({}),
+            getStores: async () => ok({}),
+            getStore: async () => ok(existingGlobalStore),
+            saveStore,
+        });
+
+        await expect(handleInit(ctx, { format: 'yaml' })).rejects.toThrow(CommanderError);
+        expect(saveStore).not.toHaveBeenCalled();
+    });
+
+    it('should allow force and skip saveStore when global store already exists', async () => {
+        const saveStore = mock(async () => ok(undefined));
+
+        const { ctx } = createContext({
+            path: '/tmp/test-config.yaml',
+            data: null,
+            stores: null,
+            settings: null,
+            initializeConfig: async () => ok(undefined),
+            getSettings: async () => ok({}),
+            getStores: async () => ok({}),
+            getStore: async () => ok(existingGlobalStore),
+            saveStore,
+        });
+
+        await expect(handleInit(ctx, { force: true, format: 'yaml' })).resolves.toBeUndefined();
+        expect(saveStore).not.toHaveBeenCalled();
+    });
+
+    it('should surface config initialization failures', async () => {
+        const { ctx } = createContext({
+            path: '/tmp/test-config.yaml',
+            data: null,
+            stores: null,
+            settings: null,
+            initializeConfig: async () =>
+                err({
+                    code: 'CONFIG_WRITE_FAILED',
+                    message: 'Failed to write config file',
+                }),
+            getSettings: async () => ok({}),
+            getStores: async () => ok({}),
+            getStore: async () => ok(null),
+            saveStore: async () => ok(undefined),
+        });
+
+        await expect(handleInit(ctx, { format: 'yaml' })).rejects.toThrow(CommanderError);
+    });
+});
+
+describe('handleInit - interactive mode', () => {
+    it('should call promptDeps.input twice when stdin is a TTY and no flags are given', async () => {
+        const inputMock = mock(async ({ default: d }: { message: string; default?: string }) => d ?? 'prompted-value');
+        const confirmMock = mock(async () => true);
+        const promptDeps: PromptDeps = { input: inputMock, confirm: confirmMock };
+
+        const { ctx } = createContext({
+            path: '/tmp/test-config.yaml',
+            data: null,
+            stores: null,
+            settings: null,
+            initializeConfig: async () => ok(undefined),
+            getSettings: async () => ok({}),
+            getStores: async () => ok({}),
+            getStore: async () => ok(null),
+            saveStore: async () => ok(undefined),
+        });
+        (ctx.stdin as unknown as { isTTY: boolean }).isTTY = true;
+
+        await handleInit(ctx, { format: 'json' }, promptDeps);
+
+        expect(inputMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('should NOT call promptDeps.input when stdin is NOT a TTY', async () => {
+        const inputMock = mock(async ({ default: d }: { message: string; default?: string }) => d ?? 'prompted-value');
+        const promptDeps: PromptDeps = { input: inputMock, confirm: mock(async () => true) };
+
+        const { ctx } = createContext({
+            path: '/tmp/test-config.yaml',
+            data: null,
+            stores: null,
+            settings: null,
+            initializeConfig: async () => ok(undefined),
+            getSettings: async () => ok({}),
+            getStores: async () => ok({}),
+            getStore: async () => ok(null),
+            saveStore: async () => ok(undefined),
+        });
+        // ctx.stdin is a PassThrough with isTTY = undefined (non-TTY)
+
+        await handleInit(ctx, { format: 'json' }, promptDeps);
+
+        expect(inputMock).not.toHaveBeenCalled();
+    });
+
+    it('should use prompted store name in saveStore call when TTY', async () => {
+        const promptedName = 'my-custom-name';
+        const inputMock = mock(async ({ message, default: d }: { message: string; default?: string }) => {
+            // Second call is for store name
+            if (message.includes('name')) return promptedName;
+            return d ?? 'default-path';
+        });
+        const promptDeps: PromptDeps = { input: inputMock, confirm: mock(async () => true) };
+
+        const saveStore = mock(async () => ok(undefined));
+        const { ctx } = createContext({
+            path: '/tmp/test-config.yaml',
+            data: null,
+            stores: null,
+            settings: null,
+            initializeConfig: async () => ok(undefined),
+            getSettings: async () => ok({}),
+            getStores: async () => ok({}),
+            getStore: async () => ok(null),
+            saveStore,
+        });
+        (ctx.stdin as unknown as { isTTY: boolean }).isTTY = true;
+
+        await handleInit(ctx, { format: 'json' }, promptDeps);
+
+        // saveStore should be called with the prompted name
+        expect(saveStore).toHaveBeenCalledWith(promptedName, expect.any(Object));
+    });
+});