@yeseh/cortex-cli 0.6.0 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yeseh/cortex-cli",
-    "version": "0.6.0",
+    "version": "0.6.4",
     "license": "MIT",
     "type": "module",
     "repository": {
@@ -34,8 +34,8 @@
         "typescript": "^5"
     },
     "dependencies": {
-        "@yeseh/cortex-core": "0.6.0",
-        "@yeseh/cortex-storage-fs": "0.6.0",
+        "@yeseh/cortex-core": "workspace:*",
+        "@yeseh/cortex-storage-fs": "workspace:*",
         "@commander-js/extra-typings": "^14.0.0",
         "@inquirer/prompts": "^8.0.0",
         "@toon-format/toon": "^1.0.0",

package/src/category/commands/create.ts

@@ -22,6 +22,7 @@ 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 {
@@ -39,7 +40,7 @@ export interface CreateCommandOptions {
 function writeCreateOutput(
     payload: { path: string; created: boolean },
     options: CreateCommandOptions,
-    stdout: NodeJS.WritableStream,
+    stdout: NodeJS.WritableStream
 ): void {
     const rawFormat = options.format;
 
@@ -49,7 +50,10 @@ function writeCreateOutput(
         return;
     }
 
-    const serialized = serializeOutput({ kind: 'created-category', value: payload }, rawFormat as OutputFormat);
+    const serialized = serializeOutput(
+        { kind: 'created-category', value: payload },
+        rawFormat as OutputFormat
+    );
     if (!serialized.ok()) {
         throwCliError({ code: 'SERIALIZE_FAILED', message: serialized.error.message });
     }
@@ -85,7 +89,7 @@ export async function handleCreate(
     path: string,
     options: CreateCommandOptions = {}
 ): Promise<void> {
-    const store = unwrapOrThrow(ctx.cortex.getStore(storeName ?? 'global'));
+    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());

package/src/context.ts

@@ -24,7 +24,7 @@ const makeAbsolute = (pathStr: string): string => {
 
 export const validateStorePath = (
     storePath: string,
-    storeName: string,
+    storeName: string
 ): Result<void, ConfigValidationError> => {
     if (!isAbsolute(storePath)) {
         return err({
@@ -65,14 +65,19 @@ export const createCliAdapterFactory = (configAdapter: FilesystemConfigAdapter)
         const stores = configAdapter.stores!;
         const storeEntry = stores[storeName];
         if (!storeEntry) {
+            const available = Object.keys(stores).join(', ') || 'none';
             throw new Error(
-                `Store '${storeName}' not found. Available stores: ${Object.keys(stores).join(', ')}`,
+                `Store '${storeName}' is not registered. Available stores: ${available}. ` +
+                    'Use --store to specify a registered store, or run `cortex store init` to create one.'
             );
         }
 
         const storePath = storeEntry.properties?.path as string | undefined;
         if (!storePath) {
-            throw new Error(`Store '${storeName}' has no path configured in properties.`);
+            throw new Error(
+                `Store '${storeName}' has no path configured. ` +
+                    'Check your cortex config or re-run `cortex store init`.'
+            );
         }
 
         return new FilesystemStorageAdapter(configAdapter, {
@@ -82,10 +87,11 @@ export const createCliAdapterFactory = (configAdapter: FilesystemConfigAdapter)
 };
 
 export const createCliConfigContext = async (
-    options: CliContextOptions = {},
+    options: CliContextOptions = {}
 ): Promise<Result<CliConfigContext, any>> => {
     const envConfigPath = process.env.CORTEX_CONFIG;
     const envConfigDir = process.env.CORTEX_CONFIG_DIR;
+    const envConfigCwd = process.env.CORTEX_CONFIG_CWD;
 
     const explicitConfigPath =
         typeof envConfigPath === 'string' && envConfigPath.length > 0
@@ -93,10 +99,10 @@ export const createCliConfigContext = async (
             : undefined;
 
     const dir = options.configDir ?? envConfigDir ?? resolve(homedir(), '.config', 'cortex');
+
     const absoluteDir = makeAbsolute(dir);
     const configPath = explicitConfigPath ?? resolve(absoluteDir, 'config.yaml');
 
-    const envConfigCwd = process.env.CORTEX_CONFIG_CWD;
     const effectiveCwd =
         options.configCwd ??
         (typeof envConfigCwd === 'string' && envConfigCwd.length > 0
@@ -109,20 +115,10 @@ export const createCliConfigContext = async (
         return initResult;
     }
 
-    const settingsResult = await configAdapter.getSettings();
-    if (!settingsResult.ok()) {
-        return settingsResult;
-    }
-
-    const storesResult = await configAdapter.getStores();
-    if (!storesResult.ok()) {
-        return storesResult;
-    }
-
     return ok({
         configAdapter,
-        settings: settingsResult.value,
-        stores: storesResult.value,
+        settings: configAdapter.settings!,
+        stores: configAdapter.stores!,
         effectiveCwd,
     });
 };
@@ -131,7 +127,7 @@ export const createCliConfigContext = async (
  * This function is used to create a context object that can be injected into command handlers for consistent access to the Cortex client and other utilities.
  */
 export const createCliCommandContext = async (
-    configDir?: string,
+    configDir?: string
 ): Promise<Result<CortexContext, any>> => {
     try {
         const configContextResult = await createCliConfigContext({
@@ -165,8 +161,7 @@ export const createCliCommandContext = async (
         };
 
         return ok(context);
-    }
-    catch (error) {
+    } catch (error) {
         return err({
             code: 'CONTEXT_CREATION_FAILED',
             message: `Unexpected error creating CLI command context: ${error instanceof Error ? error.message : String(error)}`,

package/src/memory/commands/add.ts

@@ -28,6 +28,7 @@ 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';
+import { resolveDefaultStore } from '../../utils/resolve-default-store.ts';
 
 /** Options parsed by Commander for the add command */
 export interface AddCommandOptions {
@@ -77,7 +78,7 @@ export async function handleAdd(
     const expiresAt = parseExpiresAt(options.expiresAt);
     const citations = options.citations ?? [];
 
-    const storeResult = ctx.cortex.getStore(storeName ?? 'global');
+    const storeResult = ctx.cortex.getStore(resolveDefaultStore(ctx, storeName));
     if (!storeResult.ok()) {
         throwCliError(storeResult.error);
     }

package/src/memory/commands/list.ts

@@ -36,6 +36,7 @@ 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';
+import { resolveDefaultStore } from '../../utils/resolve-default-store.ts';
 
 /**
  * Options for the list command.
@@ -116,7 +117,7 @@ export async function handleList(
         throwCliError(categoryResult.error);
     }
 
-    const storeResult = ctx.cortex.getStore(storeName ?? 'global');
+    const storeResult = ctx.cortex.getStore(resolveDefaultStore(ctx, storeName));
     if (!storeResult.ok()) {
         throwCliError(storeResult.error);
     }

package/src/memory/commands/move.ts

@@ -17,6 +17,7 @@ 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';
+import { resolveDefaultStore } from '../../utils/resolve-default-store.ts';
 
 /** Options for the move command. */
 export interface MoveCommandOptions {
@@ -50,7 +51,7 @@ export async function handleMove(
         throwCliError(toResult.error);
     }
 
-    const storeResult = ctx.cortex.getStore(storeName ?? 'global');
+    const storeResult = ctx.cortex.getStore(resolveDefaultStore(ctx, storeName));
     if (!storeResult.ok()) {
         throwCliError(storeResult.error);
     }
@@ -81,7 +82,10 @@ export async function handleMove(
     } else {
         const format = rawFormat as OutputFormat;
         const serialized = serializeOutput(
-            { kind: 'moved-memory', value: { from: fromResult.value.toString(), to: toResult.value.toString() } },
+            {
+                kind: 'moved-memory',
+                value: { from: fromResult.value.toString(), to: toResult.value.toString() },
+            },
             format
         );
         if (!serialized.ok()) {

package/src/memory/commands/remove.ts

@@ -18,6 +18,7 @@ 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';
+import { resolveDefaultStore } from '../../utils/resolve-default-store.ts';
 
 /** Options for the remove command. */
 export interface RemoveCommandOptions {
@@ -44,7 +45,7 @@ export async function handleRemove(
         throwCliError(pathResult.error);
     }
 
-    const storeResult = ctx.cortex.getStore(storeName ?? 'global');
+    const storeResult = ctx.cortex.getStore(resolveDefaultStore(ctx, storeName));
     if (!storeResult.ok()) {
         throwCliError(storeResult.error);
     }
@@ -74,7 +75,10 @@ export async function handleRemove(
         out.write(`Removed memory ${pathResult.value.toString()}.\n`);
     } else {
         const format = rawFormat as OutputFormat;
-        const serialized = serializeOutput({kind: 'path', value: { path: pathResult.value.toString() }}, format);
+        const serialized = serializeOutput(
+            { kind: 'path', value: { path: pathResult.value.toString() } },
+            format
+        );
         if (!serialized.ok()) {
             throwCliError({ code: 'SERIALIZE_FAILED', message: serialized.error.message });
         }

package/src/memory/commands/show.ts

@@ -28,6 +28,7 @@ import { defaultTokenizer, MemoryPath, type CortexContext } from '@yeseh/cortex-
 import { type StoreClient } from '@yeseh/cortex-core/store';
 import { serializeOutput, type OutputMemory, type OutputFormat } from '../../output.ts';
 import { createCliCommandContext } from '../../context.ts';
+import { resolveDefaultStore } from '../../utils/resolve-default-store.ts';
 
 /**
  * Options for the show command.
@@ -80,7 +81,7 @@ export async function handleShow(
         throwCliError(pathResult.error);
     }
 
-    const storeResult = ctx.cortex.getStore(storeName ?? 'global');
+    const storeResult = ctx.cortex.getStore(resolveDefaultStore(ctx, storeName));
     if (!storeResult.ok()) {
         throwCliError(storeResult.error);
     }
@@ -126,7 +127,7 @@ export async function handleShow(
     };
 
     const format = (options.format as OutputFormat) ?? 'yaml';
-    const serialized = serializeOutput({kind: 'memory', value: outputMemory}, format);
+    const serialized = serializeOutput({ kind: 'memory', value: outputMemory }, format);
     if (!serialized.ok()) {
         throwCliError({ code: 'SERIALIZE_FAILED', message: serialized.error.message });
     }

package/src/memory/commands/update.ts

@@ -33,6 +33,7 @@ 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';
+import { resolveDefaultStore } from '../../utils/resolve-default-store.ts';
 
 /** Options parsed by Commander for the update command */
 export interface UpdateCommandOptions {
@@ -148,7 +149,7 @@ export async function handleUpdate(
     const expiresAt = parseUpdateExpiresAt(options.expiresAt);
     const updates = buildUpdates(content, tags, expiresAt, options.citation);
 
-    const storeResult = ctx.cortex.getStore(storeName ?? 'global');
+    const storeResult = ctx.cortex.getStore(resolveDefaultStore(ctx, storeName));
     if (!storeResult.ok()) {
         throwCliError(storeResult.error);
     }

package/src/observability.spec.ts

@@ -27,22 +27,17 @@ describe('createCliLogger', () => {
     });
 
     describe('info()', () => {
-        it('should write info log to stderr as JSON', () => {
+        it('should write human-friendly info log to stderr', () => {
             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();
+            expect(stderrLines[0]).toBe('INFO: hello world\n');
         });
 
         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);
+            expect(stderrLines[0]).toBe('INFO: test store=default count=5\n');
         });
     });
 
@@ -51,9 +46,7 @@ describe('createCliLogger', () => {
             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');
+            expect(stderrLines[0]).toBe('WARN: warning message\n');
         });
     });
 
@@ -62,25 +55,20 @@ describe('createCliLogger', () => {
             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');
+            expect(stderrLines[0]).toBe('ERROR: something failed error=boom\n');
         });
 
         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');
+            expect(stderrLines[0]).toBe('ERROR: failed error="string error"\n');
         });
 
         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();
+            expect(stderrLines[0]).toBe('ERROR: failed\n');
         });
     });
 
@@ -97,8 +85,7 @@ describe('createCliLogger', () => {
             const logger = createCliLogger();
             logger.debug('debug message');
             expect(stderrLines.length).toBe(1);
-            const parsed = JSON.parse(stderrLines[0]!);
-            expect(parsed.level).toBe('debug');
+            expect(stderrLines[0]).toBe('DEBUG: debug message\n');
         });
 
         it('should write debug output when DEBUG includes cortex alongside other values', () => {

package/src/observability.ts

@@ -1,5 +1,5 @@
 /**
- * CLI observability — plain ConsoleLogger writing structured JSON to stderr.
+ * CLI observability — plain ConsoleLogger writing human-readable lines to stderr.
  *
  * No OTel SDK dependency — keeps the CLI binary small.
  * Debug output is gated by the `DEBUG=cortex` environment variable.
@@ -11,7 +11,7 @@ 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
+ * Writes human-readable log lines to stderr (not stdout) to avoid
  * polluting piped command output. Debug output is gated by the
  * `DEBUG=cortex` environment variable.
  *
@@ -21,7 +21,7 @@ import type { Logger } from '@yeseh/cortex-core';
  * ```typescript
  * const logger = createCliLogger();
  * logger.info('Starting command', { store: 'global' });
- * // → {"ts":"2024-01-01T00:00:00.000Z","level":"info","msg":"Starting command","store":"global"}
+ * // → INFO: Starting command store=global
  * ```
  *
  * @example
@@ -34,10 +34,27 @@ export const createCliLogger = (): Logger => {
     const debugEnabled =
         typeof process.env.DEBUG === 'string' && process.env.DEBUG.includes('cortex');
 
+    const stringifyMetaValue = (value: unknown): string => {
+        if (typeof value === 'string') {
+            return value.includes(' ') ? JSON.stringify(value) : value;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean' || value === null) {
+            return String(value);
+        }
+        return JSON.stringify(value);
+    };
+
+    const formatMeta = (meta?: Record<string, unknown>): string => {
+        if (!meta || Object.keys(meta).length === 0) return '';
+        return Object.entries(meta)
+            .map(([key, value]) => `${key}=${stringifyMetaValue(value)}`)
+            .join(' ');
+    };
+
     const write = (level: string, msg: string, meta?: Record<string, unknown>): void => {
-        process.stderr.write(
-            JSON.stringify({ ts: new Date().toISOString(), level, msg, ...meta }) + '\n'
-        );
+        const line = `${level.toUpperCase()}: ${msg}`;
+        const metaText = formatMeta(meta);
+        process.stderr.write(metaText.length > 0 ? `${line} ${metaText}\n` : `${line}\n`);
     };
 
     return {
@@ -53,7 +70,9 @@ export const createCliLogger = (): Logger => {
         error(msg: string, err?: Error | unknown, meta?: Record<string, unknown>): void {
             const errMeta =
                 err instanceof Error
-                    ? { error: err.message, stack: err.stack }
+                    ? debugEnabled
+                        ? { error: err.message, stack: err.stack }
+                        : { error: err.message }
                     : err !== null && err !== undefined
                       ? { error: String(err) }
                       : {};

package/src/program.ts

@@ -65,7 +65,7 @@ export const runProgram = async (): Promise<void> => {
         // This catch handles any unexpected errors that slip through.
         const logger = createCliLogger();
         if (error instanceof Error) {
-            logger.error(`Error: ${error.message}`, error);
+            logger.error(error.message);
         }
         else {
             logger.error('An unexpected error occurred');