@yeseh/cortex-cli 0.6.0

package/src/memory/commands/update.ts

@@ -0,0 +1,229 @@
+/**
+ * Memory update command implementation using Commander.js.
+ *
+ * Updates an existing memory at the specified path with new content, tags,
+ * or expiration date.
+ *
+ * @example
+ * ```bash
+ * # Update memory content inline
+ * cortex memory update project/tech-stack --content "Updated stack: TypeScript"
+ *
+ * # Update memory content from a file
+ * cortex memory update project/notes --file ./updated-notes.md
+ *
+ * # Update tags
+ * cortex memory update project/tech-stack --tags "typescript,nodejs,updated"
+ *
+ * # Update expiration date
+ * cortex memory update project/temp --expires-at "2026-12-31T00:00:00Z"
+ *
+ * # Clear expiration date
+ * cortex memory update project/temp --no-expires-at
+ *
+ * # Update from a specific store
+ * cortex memory --store work update project/notes --content "New content"
+ * ```
+ */
+
+import { Command } from '@commander-js/extra-typings';
+import { throwCliError } from '../../errors.ts';
+import { MemoryPath, type CortexContext, type UpdateMemoryInput } from '@yeseh/cortex-core';
+import { resolveInput as resolveCliContent } from '../../utils/input.ts';
+import { parseExpiresAt, parseTags } from '../parsing.ts';
+import { createCliCommandContext } from '../../context.ts';
+import { serializeOutput, type OutputFormat } from '../../output.ts';
+
+/** Options parsed by Commander for the update command */
+export interface UpdateCommandOptions {
+    content?: string;
+    file?: string;
+    tags?: string[];
+    /**
+     * Expiration date from Commander.js option parsing.
+     * - `string` — ISO 8601 date provided via `--expires-at <date>`
+     * - `false` — expiration cleared via `--no-expires-at` negation flag
+     * - `undefined` (omitted) — keep the existing value unchanged
+     */
+    expiresAt?: string | false;
+    citation?: string[];
+    format?: string;
+}
+
+const parseUpdateExpiresAt = (raw?: string | false): Date | null | undefined => {
+    if (raw === false) {
+        return null;
+    }
+
+    if (!raw) {
+        return undefined;
+    }
+
+    return parseExpiresAt(raw);
+};
+
+const resolveUpdateContent = async (
+    ctx: CortexContext,
+    options: UpdateCommandOptions
+): Promise<string | null> => {
+    if (options.content === undefined && options.file === undefined) {
+        return null;
+    }
+
+    const content = await resolveCliContent({
+        content: options.content,
+        filePath: options.file,
+        stream: ctx.stdin,
+        // `memory update` does not read stdin.
+        stdinRequested: false,
+    });
+
+    if (!content.ok()) {
+        throwCliError(content.error);
+    }
+
+    if (!content.value.content) {
+        throwCliError({
+            code: 'MISSING_CONTENT',
+            message: 'Memory content is required via --content or --file.',
+        });
+    }
+
+    return content.value.content;
+};
+
+const buildUpdates = (
+    content: string | null,
+    tags: string[] | undefined,
+    expiresAt: Date | null | undefined,
+    citations: string[] | undefined
+): UpdateMemoryInput => {
+    const updates: UpdateMemoryInput = {};
+    if (content !== null) {
+        updates.content = content;
+    }
+    if (tags !== undefined) {
+        updates.tags = tags;
+    }
+    if (expiresAt !== undefined) {
+        updates.expiresAt = expiresAt;
+    }
+    if (citations !== undefined) {
+        updates.citations = citations;
+    }
+
+    if (Object.keys(updates).length === 0) {
+        throwCliError({
+            code: 'INVALID_ARGUMENTS',
+            message:
+                'No updates provided. Use --content, --file, --tags, --citation, or expiry flags.',
+        });
+    }
+
+    return updates;
+};
+
+/**
+ * Handler for the memory update 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 update (e.g., "project/tech-stack")
+ * @param options - Command options from Commander
+ */
+export async function handleUpdate(
+    ctx: CortexContext,
+    storeName: string | undefined,
+    path: string,
+    options: UpdateCommandOptions
+): Promise<void> {
+    const pathResult = MemoryPath.fromString(path);
+    if (!pathResult.ok()) {
+        throwCliError(pathResult.error);
+    }
+
+    const content = await resolveUpdateContent(ctx, options);
+    const tags = options.tags === undefined ? undefined : parseTags(options.tags);
+    const expiresAt = parseUpdateExpiresAt(options.expiresAt);
+    const updates = buildUpdates(content, tags, expiresAt, options.citation);
+
+    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 updateResult = await memoryClient.update(updates);
+    if (!updateResult.ok()) {
+        throwCliError(updateResult.error);
+    }
+
+    const memory = updateResult.value;
+    const stdout = ctx.stdout ?? process.stdout;
+
+    const rawFormat = options.format;
+    if (!rawFormat) {
+        stdout.write(`Updated memory ${memory.path.toString()}.\n`);
+    } else {
+        const format = rawFormat as OutputFormat;
+        const serialized = serializeOutput(
+            {
+                kind: 'memory',
+                value: {
+                    path: memory.path.toString(),
+                    metadata: memory.metadata,
+                    content: memory.content,
+                },
+            },
+            format
+        );
+        if (!serialized.ok()) {
+            throwCliError({ code: 'SERIALIZE_FAILED', message: serialized.error.message });
+        }
+        stdout.write(serialized.value + '\n');
+    }
+}
+
+/**
+ * The `memory update` subcommand.
+ *
+ * Updates an existing memory at the specified path. Can update:
+ * - Content via `--content` flag for inline text or `--file` to read from a file
+ * - Tags via `--tags` flag (replaces existing tags)
+ * - Expiration via `--expires-at` or `--no-expires-at`
+ *
+ * The `--store` option is inherited from the parent `memory` command.
+ */
+export const updateCommand = new Command('update')
+    .description('Update an existing memory')
+    .argument('<path>', 'Memory path to update')
+    .option('-c, --content <text>', 'New memory content as inline text')
+    .option('-f, --file <filepath>', 'Read new content from a file')
+    .option('-t, --tags <value...>', 'Tags (can be repeated or comma-separated, replaces existing)')
+    .option('-e, --expires-at <date>', 'New expiration date (ISO 8601)')
+    .option('--no-expires-at', 'Remove expiration date')
+    .option('--citation <value...>', 'Citation references (replaces existing)')
+    .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 handleUpdate(context.value, parentOpts?.store, path, options);
+    });

package/src/memory/index.spec.ts

@@ -0,0 +1,59 @@
+/**
+ * Unit tests for memory command group wiring.
+ *
+ * Verifies that the `memory` command group is correctly configured with
+ * the expected name, description, options, and subcommands.
+ *
+ * @module cli/memory/index.spec
+ */
+
+import { describe, it, expect } from 'bun:test';
+
+import { memoryCommand } from './index.ts';
+
+describe('memoryCommand', () => {
+    it('should have name "memory"', () => {
+        expect(memoryCommand.name()).toBe('memory');
+    });
+
+    it('should have description', () => {
+        expect(memoryCommand.description()).toBeTruthy();
+    });
+
+    it('should have --store option', () => {
+        const options = memoryCommand.options;
+        const storeOption = options.find((o) => o.long === '--store');
+        expect(storeOption).toBeDefined();
+        expect(storeOption?.short).toBe('-s');
+    });
+
+    it('should have "add" subcommand registered', () => {
+        const names = memoryCommand.commands.map((c) => c.name());
+        expect(names).toContain('add');
+    });
+
+    it('should have "show" subcommand registered', () => {
+        const names = memoryCommand.commands.map((c) => c.name());
+        expect(names).toContain('show');
+    });
+
+    it('should have "update" subcommand registered', () => {
+        const names = memoryCommand.commands.map((c) => c.name());
+        expect(names).toContain('update');
+    });
+
+    it('should have "remove" subcommand registered', () => {
+        const names = memoryCommand.commands.map((c) => c.name());
+        expect(names).toContain('remove');
+    });
+
+    it('should have "move" subcommand registered', () => {
+        const names = memoryCommand.commands.map((c) => c.name());
+        expect(names).toContain('move');
+    });
+
+    it('should have "list" subcommand registered', () => {
+        const names = memoryCommand.commands.map((c) => c.name());
+        expect(names).toContain('list');
+    });
+});

package/src/memory/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Memory command group for the CLI.
+ *
+ * This module defines the `memory` command group, which provides operations
+ * for managing memories in the Cortex memory system. The `--store` option
+ * is defined at the group level and inherited by all subcommands.
+ *
+ * @example
+ * ```bash
+ * # Use default store
+ * cortex memory add project/notes --content "Hello"
+ *
+ * # Use specific store
+ * cortex memory --store my-store add project/notes --content "Hello"
+ * cortex memory -s my-store list
+ * ```
+ */
+
+import { Command } from '@commander-js/extra-typings';
+
+import { addCommand } from './commands/add.ts';
+import { showCommand } from './commands/show.ts';
+import { updateCommand } from './commands/update.ts';
+import { removeCommand } from './commands/remove.ts';
+import { moveCommand } from './commands/move.ts';
+import { listCommand } from './commands/list.ts';
+
+/**
+ * The `memory` command group.
+ *
+ * Provides memory 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 memoryCommand = new Command('memory')
+    .description('Memory operations')
+    .option('-s, --store <name>', 'Use a specific named store');
+
+memoryCommand.addCommand(addCommand);
+memoryCommand.addCommand(showCommand);
+memoryCommand.addCommand(updateCommand);
+memoryCommand.addCommand(removeCommand);
+memoryCommand.addCommand(moveCommand);
+memoryCommand.addCommand(listCommand);

package/src/memory/parsing.spec.ts

@@ -0,0 +1,105 @@
+/**
+ * Unit tests for memory/parsing.ts
+ *
+ * @module cli/memory/parsing.spec
+ */
+
+import { describe, it, expect } from 'bun:test';
+import { parseTags, parseExpiresAt } from './parsing';
+import { expectInvalidArgumentError } from '../test-helpers.spec';
+
+// ============================================================================
+// parseTags
+// ============================================================================
+
+describe('parseTags', () => {
+    it('should return empty array for undefined input', () => {
+        expect(parseTags(undefined)).toEqual([]);
+    });
+
+    it('should return empty array for empty array input', () => {
+        expect(parseTags([])).toEqual([]);
+    });
+
+    it('should split comma-separated tags from a single string', () => {
+        expect(parseTags(['foo,bar,baz'])).toEqual([
+            'foo',
+            'bar',
+            'baz',
+        ]);
+    });
+
+    it('should handle multiple string entries in the array', () => {
+        expect(parseTags([
+            'foo', 'bar',
+        ])).toEqual([
+            'foo', 'bar',
+        ]);
+    });
+
+    it('should trim whitespace from each tag', () => {
+        expect(parseTags([' foo , bar , baz '])).toEqual([
+            'foo',
+            'bar',
+            'baz',
+        ]);
+    });
+
+    it('should filter empty strings after splitting and trimming', () => {
+        expect(parseTags([
+            ',,,', '  ,  ',
+        ])).toEqual([]);
+    });
+
+    it('should preserve duplicate tags without deduplication', () => {
+        expect(parseTags([
+            'foo,foo', 'foo',
+        ])).toEqual([
+            'foo',
+            'foo',
+            'foo',
+        ]);
+    });
+});
+
+// ============================================================================
+// parseExpiresAt
+// ============================================================================
+
+describe('parseExpiresAt', () => {
+    it('should return undefined for undefined input', () => {
+        expect(parseExpiresAt(undefined)).toBeUndefined();
+    });
+
+    it('should return undefined for empty string', () => {
+        expect(parseExpiresAt('')).toBeUndefined();
+    });
+
+    it('should return a Date for valid ISO 8601 string', () => {
+        const result = parseExpiresAt('2025-12-31T23:59:59.000Z');
+        expect(result).toBeInstanceOf(Date);
+        expect(result!.toISOString()).toBe('2025-12-31T23:59:59.000Z');
+    });
+
+    it('should return a Date for valid date-only string "2025-12-31"', () => {
+        const result = parseExpiresAt('2025-12-31');
+        expect(result).toBeInstanceOf(Date);
+        expect(result!.getFullYear()).toBe(2025);
+        expect(result!.getMonth()).toBe(11); // 0-indexed December
+        expect(result!.getDate()).toBe(31);
+    });
+
+    it('should throw InvalidArgumentError for invalid date string "not-a-date"', async () => {
+        await expectInvalidArgumentError(
+            () => parseExpiresAt('not-a-date'),
+            'Invalid expiration date format',
+        );
+    });
+
+    it('should throw InvalidArgumentError for garbage string "abc123"', async () => {
+        await expectInvalidArgumentError(
+            () => parseExpiresAt('abc123'),
+            'Invalid expiration date format',
+        );
+    });
+});

package/src/memory/parsing.ts

@@ -0,0 +1,22 @@
+import { throwCliError } from '../errors';
+
+export const parseTags = (raw?: string[]): string[] =>
+    raw
+        ? raw
+            .flatMap((tag) => tag.split(','))
+            .map((tag) => tag.trim())
+            .filter(Boolean)
+        : [];
+
+export const parseExpiresAt = (raw?: string): Date | undefined => {
+    if (!raw) {
+        return undefined;
+    }
+
+    const parsed = new Date(raw);
+    if (Number.isNaN(parsed.getTime())) {
+        throwCliError({ code: 'INVALID_ARGUMENTS', message: 'Invalid expiration date format' });
+    }
+
+    return parsed;
+};

package/src/observability.spec.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test';
+import { createCliLogger } from './observability.ts';
+
+describe('createCliLogger', () => {
+    let stderrLines: string[];
+    let origWrite: typeof process.stderr.write;
+    let origDebugEnv: string | undefined;
+
+    beforeEach(() => {
+        stderrLines = [];
+        origWrite = process.stderr.write.bind(process.stderr);
+        origDebugEnv = process.env.DEBUG;
+        process.stderr.write = ((chunk: string | Uint8Array) => {
+            stderrLines.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString());
+            return true;
+        }) as any;
+    });
+
+    afterEach(() => {
+        process.stderr.write = origWrite;
+        if (origDebugEnv === undefined) {
+            delete process.env.DEBUG;
+        }
+        else {
+            process.env.DEBUG = origDebugEnv;
+        }
+    });
+
+    describe('info()', () => {
+        it('should write info log to stderr as JSON', () => {
+            const logger = createCliLogger();
+            logger.info('hello world');
+            expect(stderrLines.length).toBe(1);
+            const parsed = JSON.parse(stderrLines[0]!);
+            expect(parsed.level).toBe('info');
+            expect(parsed.msg).toBe('hello world');
+            expect(parsed.ts).toBeDefined();
+        });
+
+        it('should include metadata in the log line', () => {
+            const logger = createCliLogger();
+            logger.info('test', { store: 'default', count: 5 });
+            const parsed = JSON.parse(stderrLines[0]!);
+            expect(parsed.store).toBe('default');
+            expect(parsed.count).toBe(5);
+        });
+    });
+
+    describe('warn()', () => {
+        it('should write warn log to stderr', () => {
+            const logger = createCliLogger();
+            logger.warn('warning message');
+            expect(stderrLines.length).toBe(1);
+            const parsed = JSON.parse(stderrLines[0]!);
+            expect(parsed.level).toBe('warn');
+            expect(parsed.msg).toBe('warning message');
+        });
+    });
+
+    describe('error()', () => {
+        it('should write error log with Error object details', () => {
+            const logger = createCliLogger();
+            logger.error('something failed', new Error('boom'));
+            expect(stderrLines.length).toBe(1);
+            const parsed = JSON.parse(stderrLines[0]!);
+            expect(parsed.level).toBe('error');
+            expect(parsed.msg).toBe('something failed');
+            expect(parsed.error).toBe('boom');
+        });
+
+        it('should handle string error argument', () => {
+            const logger = createCliLogger();
+            logger.error('failed', 'string error');
+            const parsed = JSON.parse(stderrLines[0]!);
+            expect(parsed.error).toBe('string error');
+        });
+
+        it('should handle missing error argument', () => {
+            const logger = createCliLogger();
+            logger.error('failed');
+            expect(stderrLines.length).toBe(1);
+            const parsed = JSON.parse(stderrLines[0]!);
+            expect(parsed.error).toBeUndefined();
+        });
+    });
+
+    describe('debug()', () => {
+        it('should suppress debug output when DEBUG env is not set', () => {
+            delete process.env.DEBUG;
+            const logger = createCliLogger();
+            logger.debug('debug message');
+            expect(stderrLines.length).toBe(0);
+        });
+
+        it('should write debug output when DEBUG=cortex', () => {
+            process.env.DEBUG = 'cortex';
+            const logger = createCliLogger();
+            logger.debug('debug message');
+            expect(stderrLines.length).toBe(1);
+            const parsed = JSON.parse(stderrLines[0]!);
+            expect(parsed.level).toBe('debug');
+        });
+
+        it('should write debug output when DEBUG includes cortex alongside other values', () => {
+            process.env.DEBUG = 'express,cortex,http';
+            const logger = createCliLogger();
+            logger.debug('debug message');
+            expect(stderrLines.length).toBe(1);
+        });
+
+        it('should suppress debug when DEBUG is set to a different value', () => {
+            process.env.DEBUG = 'express';
+            const logger = createCliLogger();
+            logger.debug('debug message');
+            expect(stderrLines.length).toBe(0);
+        });
+    });
+
+    describe('Logger interface compliance', () => {
+        it('should not write to stdout', () => {
+            const stdoutLines: string[] = [];
+            const origStdoutWrite = process.stdout.write.bind(process.stdout);
+            process.stdout.write = ((chunk: string | Uint8Array) => {
+                stdoutLines.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString());
+                return true;
+            }) as any;
+            try {
+                const logger = createCliLogger();
+                logger.info('test');
+                logger.warn('test');
+                logger.error('test');
+                expect(stdoutLines.length).toBe(0);
+            }
+            finally {
+                process.stdout.write = origStdoutWrite;
+            }
+        });
+    });
+});

package/src/observability.ts

@@ -0,0 +1,63 @@
+/**
+ * CLI observability — plain ConsoleLogger writing structured JSON to stderr.
+ *
+ * No OTel SDK dependency — keeps the CLI binary small.
+ * Debug output is gated by the `DEBUG=cortex` environment variable.
+ *
+ * @module cli/observability
+ */
+import type { Logger } from '@yeseh/cortex-core';
+
+/**
+ * Creates a plain console logger for CLI usage.
+ *
+ * Writes structured JSON log lines to stderr (not stdout) to avoid
+ * polluting piped command output. Debug output is gated by the
+ * `DEBUG=cortex` environment variable.
+ *
+ * @returns Logger instance writing to stderr
+ *
+ * @example
+ * ```typescript
+ * const logger = createCliLogger();
+ * logger.info('Starting command', { store: 'global' });
+ * // → {"ts":"2024-01-01T00:00:00.000Z","level":"info","msg":"Starting command","store":"global"}
+ * ```
+ *
+ * @example
+ * ```bash
+ * # Enable debug output
+ * DEBUG=cortex cortex memory list
+ * ```
+ */
+export const createCliLogger = (): Logger => {
+    const debugEnabled =
+        typeof process.env.DEBUG === 'string' && process.env.DEBUG.includes('cortex');
+
+    const write = (level: string, msg: string, meta?: Record<string, unknown>): void => {
+        process.stderr.write(
+            JSON.stringify({ ts: new Date().toISOString(), level, msg, ...meta }) + '\n'
+        );
+    };
+
+    return {
+        debug(msg: string, meta?: Record<string, unknown>): void {
+            if (debugEnabled) write('debug', msg, meta);
+        },
+        info(msg: string, meta?: Record<string, unknown>): void {
+            write('info', msg, meta);
+        },
+        warn(msg: string, meta?: Record<string, unknown>): void {
+            write('warn', msg, meta);
+        },
+        error(msg: string, err?: Error | unknown, meta?: Record<string, unknown>): void {
+            const errMeta =
+                err instanceof Error
+                    ? { error: err.message, stack: err.stack }
+                    : err !== null && err !== undefined
+                      ? { error: String(err) }
+                      : {};
+            write('error', msg, { ...meta, ...errMeta });
+        },
+    };
+};