@yeseh/cortex-cli 0.6.8 → 0.6.10

package/src/category/commands/create.ts

@@ -1,119 +0,0 @@
-/**
- * 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';
-import { resolveDefaultStore } from '../../utils/resolve-default-store.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(resolveDefaultStore(ctx, storeName)));
-    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

@@ -1,24 +0,0 @@
-/**
- * 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

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

package/src/commands/init.ts

@@ -1,301 +0,0 @@
-/**
- * Init command for initializing the global cortex configuration store.
- *
- * Creates the global config store at ~/.config/cortex/ with:
- * - config.yaml: Global configuration with default settings
- * - stores.yaml: Store registry with a 'global' store pointing to the memory directory
- * - memory/: Default store with 'global' and 'projects' categories
- *
- * @example
- * ```bash
- * # Initialize global cortex configuration
- * cortex init
- *
- * # Reinitialize even if already initialized
- * cortex init --force
- * ```
- */
-
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
-import { Command } from '@commander-js/extra-typings';
-import { throwCliError } from '../errors.ts';
-import {
-    serializeOutput,
-    type OutputFormat,
-    type OutputInit,
-    type OutputPayload,
-} from '../output.ts';
-import { defaultGlobalStoreCategories } from '@yeseh/cortex-core/category';
-import {
-    configCategoriesToStoreCategories,
-    getDefaultSettings,
-    type CortexConfig,
-    type CortexContext,
-    type StoreData,
-} from '@yeseh/cortex-core';
-import { createCliCommandContext } from '../context.ts';
-import { isTTY, defaultPromptDeps, type PromptDeps } from '../utils/prompts.ts';
-
-/**
- * Options for the init command.
- */
-export interface InitCommandOptions {
-    /** Reinitialize even if already initialized */
-    force?: boolean;
-    /** Output format (yaml, json, toon) */
-    format?: string;
-}
-
-/**
- * The `init` command for initializing the global cortex configuration.
- *
- * Creates the global config store at ~/.config/cortex/ with default settings
- * and store registry.
- *
- * @example
- * ```bash
- * cortex init              # Initialize global config
- * cortex init --force      # Reinitialize even if exists
- * ```
- */
-export const initCommand = new Command('init')
-    .description('Initialize global cortex configuration')
-    .option('-F, --force', 'Reinitialize even if already initialized')
-    .option('-o, --format <format>', 'Output format (yaml, json, toon)', 'yaml')
-    .action(async (options) => {
-        const context = await createCliCommandContext();
-        if (!context.ok()) {
-            throwCliError({
-                code: 'CONTEXT_CREATION_FAILED',
-                message: `Failed to create command context: ${context.error.message}`,
-            });
-        }
-        await handleInit(context.value, options);
-    });
-
-/**
- * Prompts the user to confirm or change the resolved global store path and name.
- *
- * Returns `resolved` unchanged when stdin is not a TTY.
- *
- * @param ctx - Cortex context used for TTY detection via `ctx.stdin`
- * @param resolved - Default store name and path to present as suggestions
- * @param promptDeps - Injectable prompt functions for testability
- * @returns Finalized store name and path (either from prompts or from `resolved`)
- */
-
-/**
- * Resolve a user-supplied path:
- * - expands a leading '~' to the user's home directory
- * - resolves relative paths to an absolute path
- */
-function resolveUserPath(userPath: string): string {
-    if (!userPath) return userPath;
-
-    let expanded = userPath;
-    if (userPath.startsWith('~')) {
-        expanded = resolve(homedir(), userPath.slice(1));
-    }
-
-    return resolve(expanded);
-}
-
-function normalizeStoreName(input: string, fallback: string): string {
-    const trimmed = input.trim();
-    if (!trimmed) return fallback;
-
-    const slug = trimmed
-        .toLowerCase()
-        .replace(/[^a-z0-9_-]+/gi, '-')
-        .replace(/^-+|-+$/g, '');
-
-    return slug || fallback;
-}
-
-function normalizeStorePath(input: string, fallback: string): string {
-    const trimmed = input.trim();
-    const base = trimmed || fallback;
-    return resolveUserPath(base);
-}
-
-async function promptInitOptions(
-    ctx: CortexContext,
-    resolved: { storeName: string; storePath: string },
-    promptDeps: PromptDeps,
-): Promise<{ storeName: string; storePath: string }> {
-    if (!isTTY(ctx.stdin)) {
-        return {
-            storeName: normalizeStoreName(resolved.storeName, resolved.storeName),
-            storePath: normalizeStorePath(resolved.storePath, resolved.storePath),
-        };
-    }
-
-    const storePathInput = await promptDeps.input({
-        message: 'Global store path:',
-        default: resolved.storePath,
-    });
-    const storeNameInput = await promptDeps.input({
-        message: 'Global store name:',
-        default: resolved.storeName,
-    });
-
-    const storeName = normalizeStoreName(storeNameInput, resolved.storeName);
-    const storePath = normalizeStorePath(storePathInput, resolved.storePath);
-    return { storePath, storeName };
-}
-
-// TODO: We should move this logic into the core package as a helper function, and just call it from the CLI command handler.
-//       Use the ConfigAdapter to initialize the config store and write the default config, instead of manually writing files here. This way we can reuse the same initialization logic in other contexts (e.g. programmatic setup, tests).
-
-/**
- * Handles the init command execution.
- *
- * This function:
- * 1. When stdin is a TTY, prompts for global store path and name confirmation
- * 2. Initializes the global cortex config store
- * 3. Creates default categories
- * 4. Outputs the result
- *
- * Interactive mode activates automatically when `ctx.stdin.isTTY === true`.
- * In non-TTY environments (CI, pipes) the defaults are used without prompting.
- *
- * @param ctx - The Cortex context (stdin TTY state used for interactive detection)
- * @param options - Command options (force, format)
- * @param promptDeps - Injectable prompt functions; defaults to real `@inquirer/prompts` functions
- * @throws {InvalidArgumentError} When arguments are invalid
- * @throws {CommanderError} When initialization fails
- *
- * @example
- * ```typescript
- * // Non-interactive (CI / scripts):
- * await handleInit(ctx, { format: 'yaml' });
- *
- * // Force interactive with test stubs:
- * const stubs: PromptDeps = {
- *     input: async ({ default: d }) => d ?? 'test',
- *     confirm: async () => true,
- * };
- * (ctx.stdin as any).isTTY = true;
- * await handleInit(ctx, {}, stubs);
- * ```
- */
-export async function handleInit(
-    ctx: CortexContext,
-    options: InitCommandOptions = {},
-    promptDeps: PromptDeps = defaultPromptDeps,
-): Promise<void> {
-    const cortexConfigDir = resolve(homedir(), '.config', 'cortex');
-    const globalStorePath = resolve(cortexConfigDir, 'memory');
-
-    const resolved = await promptInitOptions(
-        ctx,
-        { storeName: 'global', storePath: globalStorePath },
-        promptDeps,
-    );
-    const finalStorePath = resolved.storePath;
-    const finalStoreName = resolved.storeName;
-
-    await initializeConfigAdapter(ctx);
-    await ensureNotInitialized(ctx, finalStoreName, finalStorePath, options.force);
-    await createGlobalStore(ctx, finalStoreName, finalStorePath);
-
-    // Build output
-    const output: OutputPayload = {
-        kind: 'init',
-        value: formatInit(finalStorePath, Object.keys(defaultGlobalStoreCategories)),
-    };
-
-    // Output result
-    const format: OutputFormat = (options.format as OutputFormat) ?? 'yaml';
-    const outputSerialized = serializeOrThrow(output, format);
-
-    const out = ctx.stdout ?? process.stdout;
-    out.write(outputSerialized.value + '\n');
-}
-
-const ensureNotInitialized = async (
-    ctx: CortexContext,
-    storeName: string,
-    globalStorePath: string,
-    force = false,
-): Promise<void> => {
-    if (force) {
-        return;
-    }
-
-    const existingStoreResult = await ctx.config.getStore(storeName);
-    if (!existingStoreResult.ok()) {
-        throwCliError(existingStoreResult.error);
-    }
-
-    if (!existingStoreResult.value) {
-        return;
-    }
-
-    throwCliError({
-        code: 'ALREADY_INITIALIZED',
-        message: `Global config store already exists at ${globalStorePath}. Use --force to reinitialize.`,
-    });
-};
-
-const initializeConfigAdapter = async (ctx: CortexContext): Promise<void> => {
-    const config: CortexConfig = {
-        settings: getDefaultSettings(),
-        stores: {},
-    };
-
-    const initConfigResult = await ctx.config.initializeConfig(config);
-    if (!initConfigResult.ok()) {
-        throwCliError(initConfigResult.error);
-    }
-};
-
-const serializeOrThrow = <T extends OutputPayload>(value: T, format: OutputFormat) => {
-    const serialized = serializeOutput(value, format);
-    if (!serialized.ok()) {
-        throwCliError(serialized.error);
-    }
-    return serialized;
-};
-
-const createGlobalStore = async (
-    ctx: CortexContext,
-    storeName: string,
-    globalStorePath: string,
-): Promise<void> => {
-    const existingStoreResult = await ctx.config.getStore(storeName);
-    if (!existingStoreResult.ok()) {
-        throwCliError(existingStoreResult.error);
-    }
-
-    if (existingStoreResult.value) {
-        return;
-    }
-
-    const templateCategories = configCategoriesToStoreCategories(
-        defaultGlobalStoreCategories,
-    ).unwrap(); // defaultGlobalStoreCategories is valid, unwrap is safe here
-
-    const globalStoreData: StoreData = {
-        kind: 'filesystem',
-        categoryMode: 'free',
-        description:
-            'Global memory store for Cortex. Use for cross-project memories and configurations.',
-        categories: templateCategories,
-        properties: {
-            path: globalStorePath,
-        },
-    };
-
-    const saveStoreResult = await ctx.config.saveStore(storeName, globalStoreData);
-    if (!saveStoreResult.ok()) {
-        throwCliError(saveStoreResult.error);
-    }
-};
-
-const formatInit = (path: string, categories: readonly string[]): OutputInit => ({
-    path,
-    categories: [...categories],
-});
-