@yeseh/cortex-cli 0.6.3 → 0.6.5

package/dist/test-helpers.spec.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Shared test helpers for CLI package unit tests.
+ *
+ * Exports reusable primitives for result construction, stream capture,
+ * clock fixtures, CLI error assertions, and mock adapter/context factories.
+ * All other spec files in this package import from this module.
+ *
+ * @module cli/_test-helpers
+ */
+import { PassThrough } from 'node:stream';
+import type { StorageAdapter, MemoryStorage, IndexStorage, CategoryStorage, ConfigStores, CortexContext } from '@yeseh/cortex-core';
+/**
+ * Constructs a minimal ok-shaped result for use in mock return values.
+ *
+ * @param value - The success value
+ * @returns A plain object compatible with ok result checks
+ *
+ * @example
+ * ```typescript
+ * const result = okResult('hello');
+ * expect(result.ok()).toBe(true);
+ * expect(result.value).toBe('hello');
+ * ```
+ */
+export declare const okResult: <T>(value: T) => {
+    ok: () => true;
+    value: T;
+};
+/**
+ * Constructs a minimal err-shaped result for use in mock return values.
+ *
+ * @param error - The error value
+ * @returns A plain object compatible with err result checks
+ *
+ * @example
+ * ```typescript
+ * const result = errResult({ code: 'NOT_FOUND', message: 'not found' });
+ * expect(result.ok()).toBe(false);
+ * ```
+ */
+export declare const errResult: <E>(error: E) => {
+    ok: () => false;
+    error: E;
+};
+/**
+ * Creates a writable PassThrough stream and a helper to capture written text.
+ *
+ * @returns An object containing the stream and a `getOutput` function
+ *
+ * @example
+ * ```typescript
+ * const { stream, getOutput } = createWritableCapture();
+ * stream.write('hello');
+ * expect(getOutput()).toBe('hello');
+ * ```
+ */
+export declare function createWritableCapture(): {
+    stream: PassThrough;
+    getOutput: () => string;
+};
+/**
+ * Creates a readable PassThrough stream pre-loaded with text.
+ *
+ * @param text - The text to pre-load into the stream
+ * @returns A PassThrough stream with the given text already written
+ *
+ * @example
+ * ```typescript
+ * const stream = createReadableFromText('user input\n');
+ * ```
+ */
+export declare function createReadableFromText(text: string): PassThrough;
+/** ISO 8601 string for the fixed test clock date */
+export declare const FIXED_NOW_ISO = "2025-06-01T12:00:00.000Z";
+/** Fixed Date instance for use in tests */
+export declare const FIXED_NOW: Date;
+/**
+ * Returns a `now` function that always returns the given ISO date.
+ *
+ * @param iso - ISO 8601 string (defaults to {@link FIXED_NOW_ISO})
+ * @returns A zero-argument function returning the fixed Date
+ *
+ * @example
+ * ```typescript
+ * const ctx = createMockContext({ now: fixedNow('2025-01-01T00:00:00.000Z') });
+ * ```
+ */
+export declare const fixedNow: (iso?: string) => (() => Date);
+/**
+ * Asserts that the given function throws an `InvalidArgumentError`.
+ *
+ * @param fn - Sync or async function expected to throw
+ * @param messagePart - Optional substring the error message must contain
+ *
+ * @example
+ * ```typescript
+ * await expectInvalidArgumentError(
+ *     () => parseMemoryPath(''),
+ *     'must not be empty',
+ * );
+ * ```
+ */
+export declare function expectInvalidArgumentError(fn: () => Promise<unknown> | unknown, messagePart?: string): Promise<void>;
+/**
+ * Asserts that the given function throws a `CommanderError`.
+ *
+ * @param fn - Sync or async function expected to throw
+ * @param codePart - Optional substring the error's `.code` must contain
+ * @param messagePart - Optional substring the error message must contain
+ *
+ * @example
+ * ```typescript
+ * await expectCommanderError(
+ *     () => handleAdd(ctx, args, 'missing-store'),
+ *     'commander.storeNotFound',
+ * );
+ * ```
+ */
+export declare function expectCommanderError(fn: () => Promise<unknown> | unknown, codePart?: string, messagePart?: string): Promise<void>;
+/**
+ * Creates a minimal mock MemoryStorage with sensible defaults.
+ *
+ * @param overrides - Partial overrides for individual methods
+ * @returns A fully-typed MemoryStorage mock
+ *
+ * @example
+ * ```typescript
+ * const memories = createMockMemoryStorage({
+ *     load: async () => ok(sampleMemory),
+ * });
+ * ```
+ */
+export declare function createMockMemoryStorage(overrides?: Partial<MemoryStorage>): MemoryStorage;
+/**
+ * Creates a minimal mock IndexStorage with sensible defaults.
+ *
+ * @param overrides - Partial overrides for individual methods
+ * @returns A fully-typed IndexStorage mock
+ *
+ * @example
+ * ```typescript
+ * const indexes = createMockIndexStorage({
+ *     load: async () => ok({ memories: [], subcategories: [] }),
+ * });
+ * ```
+ */
+export declare function createMockIndexStorage(overrides?: Partial<IndexStorage>): IndexStorage;
+/**
+ * Creates a minimal mock CategoryStorage with sensible defaults.
+ *
+ * @param overrides - Partial overrides for individual methods
+ * @returns A fully-typed CategoryStorage mock
+ *
+ * @example
+ * ```typescript
+ * const categories = createMockCategoryStorage({
+ *     exists: async () => ok(true),
+ * });
+ * ```
+ */
+export declare function createMockCategoryStorage(overrides?: Partial<CategoryStorage>): CategoryStorage;
+/**
+ * Creates a minimal mock StorageAdapter composed of mock sub-adapters.
+ *
+ * @param overrides - Partial overrides for individual sub-adapters
+ * @returns A fully-typed StorageAdapter mock
+ *
+ * @example
+ * ```typescript
+ * const adapter = createMockStorageAdapter({
+ *     memories: createMockMemoryStorage({ load: async () => ok(null) }),
+ * });
+ * ```
+ */
+export declare function createMockStorageAdapter(overrides?: Partial<StorageAdapter>): StorageAdapter;
+/** Options for {@link createMockContext} */
+export interface MockContextOptions {
+    /** Override the storage adapter (defaults to {@link createMockStorageAdapter}) */
+    adapter?: StorageAdapter;
+    /** Override the store configuration (defaults to a single in-memory mock store) */
+    stores?: ConfigStores;
+    /** Override the clock (defaults to {@link fixedNow}) */
+    now?: () => Date;
+    /** Override the current working directory */
+    cwd?: string;
+}
+/** Result of {@link createMockContext} */
+export interface MockContextResult {
+    ctx: CortexContext;
+    stdout: PassThrough;
+    stdin: PassThrough;
+}
+/**
+ * Creates a {@link CortexContext} backed by a real Cortex.init() with a mock adapter.
+ *
+ * @param overrides - Optional overrides for adapter, stores, clock, and cwd
+ * @returns An object with the context and the raw stdout/stdin PassThrough streams
+ *
+ * @example
+ * ```typescript
+ * const { ctx, stdout } = createMockContext();
+ * await handleAdd(ctx, args, 'default', {});
+ * expect(captureOutput(stdout)).toContain('Memory added');
+ * ```
+ */
+export declare function createMockContext(overrides?: MockContextOptions): MockContextResult;
+/**
+ * Reads all buffered output from a PassThrough stream synchronously.
+ *
+ * Drains already-buffered data without consuming future writes.
+ * Useful for asserting output after a handler has finished writing.
+ *
+ * @param stream - The PassThrough stream to drain
+ * @returns The concatenated string of all buffered chunks
+ *
+ * @example
+ * ```typescript
+ * const { ctx, stdout } = createMockContext();
+ * await handleList(ctx, {}, 'default', {});
+ * expect(captureOutput(stdout)).toContain('No memories found');
+ * ```
+ */
+export declare function captureOutput(stream: PassThrough): string;
+//# sourceMappingURL=test-helpers.spec.d.ts.map

package/dist/test-helpers.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.spec.d.ts","sourceRoot":"","sources":["../src/test-helpers.spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EACR,cAAc,EACd,aAAa,EACb,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,aAAa,EAChB,MAAM,oBAAoB,CAAC;AAO5B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG;IAAE,EAAE,EAAE,MAAM,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAG/D,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG;IAAE,EAAE,EAAE,MAAM,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAGjE,CAAC;AAMH;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,IAAI;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,MAAM,MAAM,CAAA;CAAE,CAOxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAIhE;AAMD,oDAAoD;AACpD,eAAO,MAAM,aAAa,6BAA6B,CAAC;AAExD,2CAA2C;AAC3C,eAAO,MAAM,SAAS,MAA0B,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,GAChB,MAAK,MAAsB,KAAG,CAAC,MAAM,IAAI,CAEzB,CAAC;AAMtB;;;;;;;;;;;;;GAaG;AACH,wBAAsB,0BAA0B,CAC5C,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,EACpC,WAAW,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CACtC,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,EACpC,QAAQ,CAAC,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAiBf;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,GAAE,OAAO,CAAC,aAAa,CAAM,GAAG,aAAa,CAY7F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,GAAE,OAAO,CAAC,YAAY,CAAM,GAAG,YAAY,CAQ1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACrC,SAAS,GAAE,OAAO,CAAC,eAAe,CAAM,GACzC,eAAe,CAQjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,GAAE,OAAO,CAAC,cAAc,CAAM,GAAG,cAAc,CAkBhG;AAED,4CAA4C;AAC5C,MAAM,WAAW,kBAAkB;IAC/B,kFAAkF;IAClF,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,mFAAmF;IACnF,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,aAAa,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,kBAAkB,GAAG,iBAAiB,CA2BnF;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAOzD"}

package/dist/tests/cli.integration.spec.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Comprehensive integration tests for the Cortex CLI with Commander.js.
+ *
+ * These tests spawn the CLI as a subprocess using Bun shell to test
+ * the CLI like a user would interact with it.
+ *
+ * The tests use local store resolution by creating a project directory
+ * with a `.cortex/memory` subdirectory structure.
+ */
+export {};
+//# sourceMappingURL=cli.integration.spec.d.ts.map

package/dist/tests/cli.integration.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.integration.spec.d.ts","sourceRoot":"","sources":["../../src/tests/cli.integration.spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/toon.d.ts

@@ -0,0 +1,197 @@
+/**
+ * TOON (Token-Oriented Object Notation) encoder.
+ *
+ * A compact serialization format optimized for LLM context consumption,
+ * achieving approximately 40% token reduction compared to JSON while
+ * improving parsing accuracy from 70% to 74% in LLM benchmarks.
+ *
+ * ## Key Features
+ *
+ * - **Tab delimiters** - Uses tabs between key-value pairs instead of JSON's
+ *   commas and braces, maximizing token efficiency
+ * - **Key folding** - Collapses nested object paths to dotted notation
+ *   (e.g., `user.profile.name` instead of nested objects)
+ * - **Tabular arrays** - Uniform object arrays use a compact header+rows format,
+ *   dramatically reducing repetition
+ *
+ * ## Format Specification
+ *
+ * | JSON Construct | TOON Equivalent |
+ * |----------------|-----------------|
+ * | `{"key": "value"}` | `key:value` |
+ * | `{"a": 1, "b": 2}` | `a:1\tb:2` |
+ * | Nested object | `parent.child:value` (with key folding) |
+ * | Uniform array | `items[N]{col1\tcol2}:\n\tval1\tval2` |
+ *
+ * ## Token Efficiency
+ *
+ * TOON reduces token count through:
+ * 1. Eliminating JSON syntax tokens (`{`, `}`, `[`, `]`, `,`, `"`)
+ * 2. Using single-character delimiters (tabs, colons)
+ * 3. Deduplicating keys in tabular array format
+ *
+ * Typical savings:
+ * - Simple objects: ~30% reduction
+ * - Nested objects with key folding: ~40% reduction
+ * - Arrays of uniform objects: ~50% reduction
+ *
+ * @module cli/toon
+ *
+ * @example Basic object encoding
+ * ```ts
+ * import { encode } from './toon';
+ *
+ * encode({ name: 'test', count: 42 });
+ * // Output: "name:test\tcount:42"
+ * ```
+ *
+ * @example Key folding for nested objects
+ * ```ts
+ * encode(
+ *   { user: { name: 'Alice', role: 'admin' } },
+ *   { keyFolding: 'safe' }
+ * );
+ * // Output: "user.name:Alice\tuser.role:admin"
+ * //
+ * // Without key folding:
+ * // "user:{name:Alice\trole:admin}"
+ * ```
+ *
+ * @example Tabular arrays (automatic for uniform object arrays)
+ * ```ts
+ * encode({
+ *   items: [
+ *     { id: 1, name: 'Widget' },
+ *     { id: 2, name: 'Gadget' },
+ *   ]
+ * });
+ * // Output:
+ * // "items[2]{id\tname}:
+ * //  \t1\tWidget
+ * //  \t2\tGadget"
+ * //
+ * // Equivalent JSON (32 tokens):
+ * // {"items":[{"id":1,"name":"Widget"},{"id":2,"name":"Gadget"}]}
+ * // TOON version (18 tokens): ~44% reduction
+ * ```
+ *
+ * @see {@link ToonOptions} for configuration options
+ * @see {@link encode} for the main encoding function
+ */
+/**
+ * Configuration options for TOON encoding.
+ *
+ * @example Using custom delimiter
+ * ```ts
+ * encode({ a: 1, b: 2 }, { delimiter: '|' });
+ * // Output: "a:1|b:2"
+ * ```
+ *
+ * @example Enabling key folding
+ * ```ts
+ * encode({ config: { debug: true } }, { keyFolding: 'safe' });
+ * // Output: "config.debug:true"
+ * ```
+ */
+export interface ToonOptions {
+    /**
+     * Character used to separate key-value pairs.
+     *
+     * The tab character (`\t`) is used by default as it provides optimal
+     * token efficiency in most LLM tokenizers (single token per delimiter).
+     *
+     * @default '\t'
+     */
+    delimiter?: string;
+    /**
+     * Controls how nested objects are serialized.
+     *
+     * - `'none'` - Nested objects are serialized inline with braces:
+     *   `parent:{child:value}`
+     * - `'safe'` - Nested paths are collapsed to dotted notation:
+     *   `parent.child:value`
+     *
+     * Key folding (`'safe'`) typically produces more compact output and is
+     * easier for LLMs to parse, but may cause key collisions if object
+     * keys contain dots.
+     *
+     * @default 'none'
+     */
+    keyFolding?: 'safe' | 'none';
+}
+/**
+ * Encodes a value to TOON format.
+ *
+ * TOON (Token-Oriented Object Notation) is a compact serialization format
+ * designed to minimize token consumption in LLM contexts while remaining
+ * human-readable and easily parseable by language models.
+ *
+ * @param value - The value to encode (must be JSON-serializable)
+ * @param options - Encoding options for customizing output format
+ * @returns TOON-encoded string representation
+ *
+ * @example Basic object encoding
+ * ```ts
+ * const data = { name: 'test', count: 42 };
+ * encode(data);
+ * // Returns: "name:test\tcount:42"
+ * //
+ * // Equivalent JSON: {"name":"test","count":42}
+ * // Token savings: ~35%
+ * ```
+ *
+ * @example Nested objects with key folding
+ * ```ts
+ * const nested = {
+ *   user: {
+ *     profile: { name: 'Alice', email: 'alice@example.com' },
+ *     settings: { theme: 'dark' }
+ *   }
+ * };
+ *
+ * // Without key folding (default):
+ * encode(nested);
+ * // Returns: "user:{profile:{name:Alice\temail:alice@example.com}\tsettings:{theme:dark}}"
+ *
+ * // With key folding:
+ * encode(nested, { keyFolding: 'safe' });
+ * // Returns: "user.profile.name:Alice\tuser.profile.email:alice@example.com\tuser.settings.theme:dark"
+ * ```
+ *
+ * @example Tabular arrays (automatic for uniform object arrays)
+ * ```ts
+ * const users = {
+ *   users: [
+ *     { id: 1, name: 'Alice', role: 'admin' },
+ *     { id: 2, name: 'Bob', role: 'user' },
+ *     { id: 3, name: 'Charlie', role: 'user' },
+ *   ]
+ * };
+ *
+ * encode(users);
+ * // Returns:
+ * // "users[3]{id\tname\trole}:
+ * //  \t1\tAlice\tadmin
+ * //  \t2\tBob\tuser
+ * //  \t3\tCharlie\tuser"
+ * //
+ * // Equivalent JSON (87 chars, ~25 tokens):
+ * // {"users":[{"id":1,"name":"Alice","role":"admin"},{"id":2,"name":"Bob","role":"user"},{"id":3,"name":"Charlie","role":"user"}]}
+ * //
+ * // TOON (67 chars, ~15 tokens): ~40% token reduction
+ * ```
+ *
+ * @example Mixed content
+ * ```ts
+ * encode({
+ *   title: 'Report',
+ *   metadata: { version: 1 },
+ *   tags: ['urgent', 'review']  // Non-uniform arrays use JSON format
+ * }, { keyFolding: 'safe' });
+ * // Returns: "title:Report\tmetadata.version:1\ttags:[\"urgent\",\"review\"]"
+ * ```
+ *
+ * @see {@link ToonOptions} for available configuration options
+ */
+export declare const encode: (value: unknown, options?: ToonOptions) => string;
+//# sourceMappingURL=toon.d.ts.map

package/dist/toon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toon.d.ts","sourceRoot":"","sources":["../src/toon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW;IACxB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAkQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,OAAO,EAAE,UAAU,WAAW,KAAG,MAO9D,CAAC"}

package/dist/toon.spec.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Unit tests for toon.ts
+ *
+ * TOON (Token-Oriented Object Notation) encoder.
+ *
+ * @module cli/toon.spec
+ */
+export {};
+//# sourceMappingURL=toon.spec.d.ts.map

package/dist/toon.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toon.spec.d.ts","sourceRoot":"","sources":["../src/toon.spec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/utils/git.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Executes a git command and returns the trimmed stdout.
+ */
+export declare const runGitCommand: (args: string[], cwd: string) => Promise<{
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+}>;
+/**
+ * Detects the git repository name from the current working directory.
+ *
+ * Uses `git rev-parse --show-toplevel` to find the repository root,
+ * then extracts the directory name as the repository name.
+ *
+ * @param cwd - The current working directory to check for git repository
+ * @returns The repository directory name, or `null` if not in a git repository
+ */
+export declare const detectGitRepoName: (cwd: string) => Promise<string | null>;
+//# sourceMappingURL=git.d.ts.map

package/dist/utils/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/utils/git.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,aAAa,GACtB,MAAM,MAAM,EAAE,EACd,KAAK,MAAM,KACZ,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAoBrD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAU,KAAK,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAQ1E,CAAC"}

package/dist/utils/git.spec.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Unit tests for utils/git.ts
+ *
+ * @module cli/utils/git.spec
+ */
+export {};
+//# sourceMappingURL=git.spec.d.ts.map

package/dist/utils/git.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.spec.d.ts","sourceRoot":"","sources":["../../src/utils/git.spec.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

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

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');