feat(memory): add registerMemoryCommand for mosaic memory CLI surface

Adds mosaic memory CLI with four subcommands: search, stats,
insights list, and preferences list. Commands accept --db flag
(or MEMORY_DB_URL/DATABASE_URL env) to connect to pgvector or
keyword adapter. Smoke tests verify command wiring without DB.

Task: CU-05-04

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

packages/memory/package.json

@@ -25,6 +25,7 @@
     "@mosaicstack/db": "workspace:*",
     "@mosaicstack/storage": "workspace:*",
     "@mosaicstack/types": "workspace:*",
+    "commander": "^13.0.0",
     "drizzle-orm": "^0.45.1"
   },
   "devDependencies": {

packages/memory/src/cli.spec.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+import { registerMemoryCommand } from './cli.js';
+
+/**
+ * Smoke test — only verifies command wiring.
+ * Does NOT open a database connection.
+ */
+describe('registerMemoryCommand', () => {
+  function buildProgram(): Command {
+    const program = new Command('mosaic');
+    program.exitOverride(); // prevent process.exit during tests
+    registerMemoryCommand(program);
+    return program;
+  }
+
+  it('registers a "memory" subcommand', () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === 'memory');
+    expect(memory).toBeDefined();
+  });
+
+  it('registers "memory search"', () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === 'memory')!;
+    const search = memory.commands.find((c) => c.name() === 'search');
+    expect(search).toBeDefined();
+  });
+
+  it('registers "memory stats"', () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === 'memory')!;
+    const stats = memory.commands.find((c) => c.name() === 'stats');
+    expect(stats).toBeDefined();
+  });
+
+  it('registers "memory insights list"', () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === 'memory')!;
+    const insights = memory.commands.find((c) => c.name() === 'insights');
+    expect(insights).toBeDefined();
+    const list = insights!.commands.find((c) => c.name() === 'list');
+    expect(list).toBeDefined();
+  });
+
+  it('registers "memory preferences list"', () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === 'memory')!;
+    const preferences = memory.commands.find((c) => c.name() === 'preferences');
+    expect(preferences).toBeDefined();
+    const list = preferences!.commands.find((c) => c.name() === 'list');
+    expect(list).toBeDefined();
+  });
+
+  it('"memory search" has --limit and --agent options', () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === 'memory')!;
+    const search = memory.commands.find((c) => c.name() === 'search')!;
+    const optNames = search.options.map((o) => o.long);
+    expect(optNames).toContain('--limit');
+    expect(optNames).toContain('--agent');
+  });
+});

packages/memory/src/cli.ts

@@ -0,0 +1,179 @@
+import type { Command } from 'commander';
+
+import type { MemoryAdapter } from './types.js';
+
+/**
+ * Build and return a connected MemoryAdapter from a connection string or
+ * the MEMORY_DB_URL / DATABASE_URL environment variable.
+ *
+ * For pgvector (postgres://...) the connection string is injected into
+ * DATABASE_URL so that PgVectorAdapter's internal createDb() picks it up.
+ *
+ * Throws with a human-readable message if no connection info is available.
+ */
+async function resolveAdapter(dbOption: string | undefined): Promise<MemoryAdapter> {
+  const connStr = dbOption ?? process.env['MEMORY_DB_URL'] ?? process.env['DATABASE_URL'];
+  if (!connStr) {
+    throw new Error(
+      'No database connection string provided. ' +
+        'Pass --db <connection-string> or set MEMORY_DB_URL / DATABASE_URL.',
+    );
+  }
+
+  // Lazy imports so the module loads cleanly without a live DB during smoke tests.
+  const { createMemoryAdapter, registerMemoryAdapter } = await import('./factory.js');
+
+  if (connStr.startsWith('postgres') || connStr.startsWith('pg')) {
+    // PgVectorAdapter reads DATABASE_URL via createDb() — inject it here.
+    process.env['DATABASE_URL'] = connStr;
+
+    const { PgVectorAdapter } = await import('./adapters/pgvector.js');
+    registerMemoryAdapter('pgvector', (cfg) => new PgVectorAdapter(cfg as never));
+    return createMemoryAdapter({ type: 'pgvector' });
+  }
+
+  // Keyword adapter backed by pglite storage; treat connStr as a data directory.
+  const { KeywordAdapter } = await import('./adapters/keyword.js');
+  const { createStorageAdapter, registerStorageAdapter } = await import('@mosaicstack/storage');
+  const { PgliteAdapter } = await import('@mosaicstack/storage');
+
+  registerStorageAdapter('pglite', (cfg) => new PgliteAdapter(cfg as never));
+
+  const storage = createStorageAdapter({ type: 'pglite', dataDir: connStr });
+
+  registerMemoryAdapter('keyword', (cfg) => new KeywordAdapter(cfg as never));
+  return createMemoryAdapter({ type: 'keyword', storage });
+}
+
+/**
+ * Register `memory` subcommands on an existing Commander program.
+ * Follows the registerQualityRails pattern from @mosaicstack/quality-rails.
+ */
+export function registerMemoryCommand(parent: Command): void {
+  const memory = parent.command('memory').description('Inspect and query the Mosaic memory layer');
+
+  // ── memory search <query> ──────────────────────────────────────────────
+  memory
+    .command('search <query>')
+    .description('Semantic search over insights')
+    .option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
+    .option('--limit <n>', 'Maximum number of results', '10')
+    .option('--agent <id>', 'Filter by agent / user ID')
+    .action(async (query: string, opts: { db?: string; limit: string; agent?: string }) => {
+      let adapter: MemoryAdapter | undefined;
+      try {
+        adapter = await resolveAdapter(opts.db);
+        const limit = parseInt(opts.limit, 10);
+        const userId = opts.agent ?? 'system';
+        const results = await adapter.searchInsights(userId, query, { limit });
+
+        if (results.length === 0) {
+          console.log('No insights found.');
+        } else {
+          for (const r of results) {
+            console.log(`[${r.id}] (score=${r.score.toFixed(3)}) ${r.content}`);
+          }
+        }
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+      } finally {
+        await adapter?.close();
+      }
+    });
+
+  // ── memory stats ──────────────────────────────────────────────────────
+  memory
+    .command('stats')
+    .description('Print memory tier info: adapter type, insight count, preference count')
+    .option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
+    .option('--agent <id>', 'User / agent ID scope for counts', 'system')
+    .action(async (opts: { db?: string; agent: string }) => {
+      let adapter: MemoryAdapter | undefined;
+      try {
+        adapter = await resolveAdapter(opts.db);
+
+        const adapterType = adapter.name;
+
+        const insightCount = await adapter
+          .searchInsights(opts.agent, '', { limit: 100000 })
+          .then((r) => r.length)
+          .catch(() => -1);
+
+        const prefCount = await adapter
+          .listPreferences(opts.agent)
+          .then((r) => r.length)
+          .catch(() => -1);
+
+        console.log(`adapter:     ${adapterType}`);
+        console.log(`insights:    ${insightCount === -1 ? 'unavailable' : String(insightCount)}`);
+        console.log(`preferences: ${prefCount === -1 ? 'unavailable' : String(prefCount)}`);
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+      } finally {
+        await adapter?.close();
+      }
+    });
+
+  // ── memory insights ───────────────────────────────────────────────────
+  const insightsCmd = memory.command('insights').description('Manage insights');
+
+  insightsCmd
+    .command('list')
+    .description('List recent insights')
+    .option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
+    .option('--limit <n>', 'Maximum number of results', '20')
+    .option('--agent <id>', 'User / agent ID scope', 'system')
+    .action(async (opts: { db?: string; limit: string; agent: string }) => {
+      let adapter: MemoryAdapter | undefined;
+      try {
+        adapter = await resolveAdapter(opts.db);
+        const limit = parseInt(opts.limit, 10);
+        const results = await adapter.searchInsights(opts.agent, '', { limit });
+
+        if (results.length === 0) {
+          console.log('No insights found.');
+        } else {
+          for (const r of results) {
+            console.log(`[${r.id}] ${r.content}`);
+          }
+        }
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+      } finally {
+        await adapter?.close();
+      }
+    });
+
+  // ── memory preferences ────────────────────────────────────────────────
+  const prefsCmd = memory.command('preferences').description('Manage stored preferences');
+
+  prefsCmd
+    .command('list')
+    .description('List stored preferences')
+    .option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
+    .option('--agent <id>', 'User / agent ID scope', 'system')
+    .option('--category <cat>', 'Filter by category')
+    .action(async (opts: { db?: string; agent: string; category?: string }) => {
+      let adapter: MemoryAdapter | undefined;
+      try {
+        adapter = await resolveAdapter(opts.db);
+        const prefs = await adapter.listPreferences(opts.agent, opts.category);
+
+        if (prefs.length === 0) {
+          console.log('No preferences found.');
+        } else {
+          for (const p of prefs) {
+            console.log(`[${p.category}] ${p.key} = ${JSON.stringify(p.value)}`);
+          }
+        }
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+      } finally {
+        await adapter?.close();
+      }
+    });
+}

packages/memory/src/index.ts

@@ -1,4 +1,5 @@
 export { createMemory, type Memory } from './memory.js';
+export { registerMemoryCommand } from './cli.js';
 export {
   createPreferencesRepo,
   type PreferencesRepo,

packages/mosaic/package.json

@@ -31,8 +31,10 @@
     "@mosaicstack/config": "workspace:*",
     "@mosaicstack/forge": "workspace:*",
     "@mosaicstack/macp": "workspace:*",
+    "@mosaicstack/memory": "workspace:*",
     "@mosaicstack/prdy": "workspace:*",
     "@mosaicstack/quality-rails": "workspace:*",
+    "@mosaicstack/queue": "workspace:*",
     "@mosaicstack/types": "workspace:*",
     "@clack/prompts": "^0.9.1",
     "commander": "^13.0.0",

packages/mosaic/src/cli.ts

@@ -3,9 +3,10 @@
 import { createRequire } from 'module';
 import { Command } from 'commander';
 import { registerBrainCommand } from '@mosaicstack/brain';
+import { registerMemoryCommand } from '@mosaicstack/memory';
 import { registerQualityRails } from '@mosaicstack/quality-rails';
+import { registerQueueCommand } from '@mosaicstack/queue';
 import { registerAgentCommand } from './commands/agent.js';
-import { registerConfigCommand } from './commands/config.js';
 import { registerMissionCommand } from './commands/mission.js';
 // prdy is registered via launch.ts
 import { registerLaunchCommands } from './commands/launch.js';
@@ -331,10 +332,6 @@ registerGatewayCommand(program);
 
 registerAgentCommand(program);
 
-// ─── config ────────────────────────────────────────────────────────────
-
-registerConfigCommand(program);
-
 // ─── mission ───────────────────────────────────────────────────────────
 
 registerMissionCommand(program);
@@ -347,6 +344,14 @@ registerBrainCommand(program);
 
 registerQualityRails(program);
 
+// ─── memory ──────────────────────────────────────────────────────────────
+
+registerMemoryCommand(program);
+
+// ─── queue ───────────────────────────────────────────────────────────────
+
+registerQueueCommand(program);
+
 // ─── update ─────────────────────────────────────────────────────────────
 
 program

packages/mosaic/src/commands/config.spec.ts

@@ -1,289 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { Command } from 'commander';
-import { registerConfigCommand } from './config.js';
-
-// ── helpers ──────────────────────────────────────────────────────────────────
-
-/** Build a fresh Command tree with the config command registered. */
-function buildProgram(): Command {
-  const program = new Command();
-  program.exitOverride(); // prevent process.exit during tests
-  registerConfigCommand(program);
-  return program;
-}
-
-/** Locate the 'config' command registered on the root program. */
-function getConfigCmd(program: Command): Command {
-  const found = program.commands.find((c) => c.name() === 'config');
-  if (!found) throw new Error('config command not found');
-  return found;
-}
-
-// ── subcommand registration ───────────────────────────────────────────────────
-
-describe('registerConfigCommand', () => {
-  it('registers a "config" command on the program', () => {
-    const program = buildProgram();
-    const names = program.commands.map((c) => c.name());
-    expect(names).toContain('config');
-  });
-
-  it('registers exactly the five required subcommands', () => {
-    const program = buildProgram();
-    const config = getConfigCmd(program);
-    const subs = config.commands.map((c) => c.name()).sort();
-    expect(subs).toEqual(['edit', 'get', 'path', 'set', 'show']);
-  });
-});
-
-// ── mock config service ───────────────────────────────────────────────────────
-
-const mockSoul = {
-  agentName: 'TestBot',
-  roleDescription: 'test role',
-  communicationStyle: 'direct' as const,
-};
-const mockUser = { userName: 'Tester', pronouns: 'they/them', timezone: 'UTC' };
-const mockTools = { credentialsLocation: '/dev/null' };
-
-const mockSvc = {
-  readSoul: vi.fn().mockResolvedValue(mockSoul),
-  readUser: vi.fn().mockResolvedValue(mockUser),
-  readTools: vi.fn().mockResolvedValue(mockTools),
-  writeSoul: vi.fn().mockResolvedValue(undefined),
-  writeUser: vi.fn().mockResolvedValue(undefined),
-  writeTools: vi.fn().mockResolvedValue(undefined),
-  syncFramework: vi.fn().mockResolvedValue(undefined),
-  readAll: vi.fn().mockResolvedValue({ soul: mockSoul, user: mockUser, tools: mockTools }),
-  getValue: vi.fn().mockResolvedValue('TestBot'),
-  setValue: vi.fn().mockResolvedValue('OldBot'),
-  getConfigPath: vi
-    .fn()
-    .mockImplementation((section?: string) =>
-      section
-        ? `/home/user/.config/mosaic/${section.toUpperCase()}.md`
-        : '/home/user/.config/mosaic',
-    ),
-  isInitialized: vi.fn().mockReturnValue(true),
-};
-
-// Mock the config-service module so commands use our mock.
-vi.mock('../config/config-service.js', () => ({
-  createConfigService: vi.fn(() => mockSvc),
-}));
-
-// Also mock child_process for the edit command.
-vi.mock('node:child_process', () => ({
-  spawnSync: vi.fn().mockReturnValue({ status: 0, error: undefined }),
-}));
-
-// ── config show ───────────────────────────────────────────────────────────────
-
-describe('config show', () => {
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
-    vi.clearAllMocks();
-    mockSvc.isInitialized.mockReturnValue(true);
-    mockSvc.readAll.mockResolvedValue({ soul: mockSoul, user: mockUser, tools: mockTools });
-  });
-
-  afterEach(() => {
-    consoleSpy.mockRestore();
-  });
-
-  it('calls readAll() and prints a table by default', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'show']);
-    expect(mockSvc.readAll).toHaveBeenCalledOnce();
-    // Should have printed something
-    expect(consoleSpy).toHaveBeenCalled();
-  });
-
-  it('prints JSON when --format json is passed', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'show', '--format', 'json']);
-    expect(mockSvc.readAll).toHaveBeenCalledOnce();
-    // Verify JSON was logged
-    const allOutput = consoleSpy.mock.calls.map((c) => c[0] as string).join('\n');
-    expect(allOutput).toContain('"agentName"');
-  });
-});
-
-// ── config get ────────────────────────────────────────────────────────────────
-
-describe('config get', () => {
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
-    vi.clearAllMocks();
-    mockSvc.isInitialized.mockReturnValue(true);
-    mockSvc.getValue.mockResolvedValue('TestBot');
-  });
-
-  afterEach(() => {
-    consoleSpy.mockRestore();
-  });
-
-  it('delegates to getValue() with the provided key', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'get', 'soul.agentName']);
-    expect(mockSvc.getValue).toHaveBeenCalledWith('soul.agentName');
-  });
-
-  it('prints the returned value', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'get', 'soul.agentName']);
-    expect(consoleSpy).toHaveBeenCalledWith('TestBot');
-  });
-});
-
-// ── config set ────────────────────────────────────────────────────────────────
-
-describe('config set', () => {
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
-    vi.clearAllMocks();
-    mockSvc.isInitialized.mockReturnValue(true);
-    mockSvc.setValue.mockResolvedValue('OldBot');
-  });
-
-  afterEach(() => {
-    consoleSpy.mockRestore();
-  });
-
-  it('delegates to setValue() with key and value', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'set', 'soul.agentName', 'NewBot']);
-    expect(mockSvc.setValue).toHaveBeenCalledWith('soul.agentName', 'NewBot');
-  });
-
-  it('prints old and new values', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'set', 'soul.agentName', 'NewBot']);
-    const output = consoleSpy.mock.calls.map((c) => c[0] as string).join('\n');
-    expect(output).toContain('OldBot');
-    expect(output).toContain('NewBot');
-  });
-});
-
-// ── config path ───────────────────────────────────────────────────────────────
-
-describe('config path', () => {
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
-    vi.clearAllMocks();
-    mockSvc.getConfigPath.mockImplementation((section?: string) =>
-      section
-        ? `/home/user/.config/mosaic/${section.toUpperCase()}.md`
-        : '/home/user/.config/mosaic',
-    );
-  });
-
-  afterEach(() => {
-    consoleSpy.mockRestore();
-  });
-
-  it('prints the mosaicHome directory when no section is specified', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'path']);
-    expect(mockSvc.getConfigPath).toHaveBeenCalledWith();
-    expect(consoleSpy).toHaveBeenCalledWith('/home/user/.config/mosaic');
-  });
-
-  it('prints the section file path when --section is given', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'path', '--section', 'soul']);
-    expect(mockSvc.getConfigPath).toHaveBeenCalledWith('soul');
-    expect(consoleSpy).toHaveBeenCalledWith('/home/user/.config/mosaic/SOUL.md');
-  });
-});
-
-// ── config edit ───────────────────────────────────────────────────────────────
-
-describe('config edit', () => {
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-  let spawnSyncMock: ReturnType<typeof vi.fn>;
-
-  beforeEach(async () => {
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
-    vi.clearAllMocks();
-    mockSvc.isInitialized.mockReturnValue(true);
-    mockSvc.readAll.mockResolvedValue({ soul: mockSoul, user: mockUser, tools: mockTools });
-    mockSvc.getConfigPath.mockImplementation((section?: string) =>
-      section
-        ? `/home/user/.config/mosaic/${section.toUpperCase()}.md`
-        : '/home/user/.config/mosaic',
-    );
-
-    // Re-import to get the mock reference
-    const cp = await import('node:child_process');
-    spawnSyncMock = cp.spawnSync as ReturnType<typeof vi.fn>;
-    spawnSyncMock.mockReturnValue({ status: 0, error: undefined });
-  });
-
-  afterEach(() => {
-    consoleSpy.mockRestore();
-  });
-
-  it('calls spawnSync with the editor binary and config path', async () => {
-    process.env['EDITOR'] = 'nano';
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'edit']);
-    expect(spawnSyncMock).toHaveBeenCalledWith(
-      'nano',
-      ['/home/user/.config/mosaic'],
-      expect.objectContaining({ stdio: 'inherit' }),
-    );
-    delete process.env['EDITOR'];
-  });
-
-  it('falls back to "vi" when EDITOR is not set', async () => {
-    delete process.env['EDITOR'];
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'edit']);
-    expect(spawnSyncMock).toHaveBeenCalledWith('vi', expect.any(Array), expect.any(Object));
-  });
-
-  it('opens the section-specific file when --section is provided', async () => {
-    process.env['EDITOR'] = 'code';
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'edit', '--section', 'soul']);
-    expect(spawnSyncMock).toHaveBeenCalledWith(
-      'code',
-      ['/home/user/.config/mosaic/SOUL.md'],
-      expect.any(Object),
-    );
-    delete process.env['EDITOR'];
-  });
-});
-
-// ── not-initialized guard ────────────────────────────────────────────────────
-
-describe('not-initialized guard', () => {
-  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
-    vi.clearAllMocks();
-    mockSvc.isInitialized.mockReturnValue(false);
-  });
-
-  afterEach(() => {
-    consoleErrorSpy.mockRestore();
-    mockSvc.isInitialized.mockReturnValue(true);
-  });
-
-  it('prints a helpful message when config is missing (show)', async () => {
-    const program = buildProgram();
-    // process.exit is intercepted; catch the resulting error from exitOverride
-    await expect(program.parseAsync(['node', 'mosaic', 'config', 'show'])).rejects.toThrow();
-    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('mosaic wizard'));
-  });
-});

packages/mosaic/src/commands/config.ts

@@ -1,206 +0,0 @@
-import { spawnSync } from 'node:child_process';
-import type { Command } from 'commander';
-import { createConfigService } from '../config/config-service.js';
-import { DEFAULT_MOSAIC_HOME } from '../constants.js';
-
-/**
- * Resolve mosaicHome from the MOSAIC_HOME env var or the default constant.
- */
-function getMosaicHome(): string {
-  return process.env['MOSAIC_HOME'] ?? DEFAULT_MOSAIC_HOME;
-}
-
-/**
- * Guard: print an error and exit(1) if config has not been initialised.
- */
-function assertInitialized(svc: ReturnType<typeof createConfigService>): void {
-  if (!svc.isInitialized()) {
-    console.error('No config found — run `mosaic wizard` first.');
-    process.exit(1);
-  }
-}
-
-/**
- * Flatten a nested object into dotted-key rows for table display.
- */
-function flattenConfig(obj: Record<string, unknown>, prefix = ''): Array<[string, string]> {
-  const rows: Array<[string, string]> = [];
-  for (const [k, v] of Object.entries(obj)) {
-    const key = prefix ? `${prefix}.${k}` : k;
-    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
-      rows.push(...flattenConfig(v as Record<string, unknown>, key));
-    } else {
-      rows.push([key, v === undefined || v === null ? '' : String(v)]);
-    }
-  }
-  return rows;
-}
-
-/**
- * Print rows as a padded ASCII table.
- */
-function printTable(rows: Array<[string, string]>): void {
-  if (rows.length === 0) {
-    console.log('(no config values)');
-    return;
-  }
-  const maxKey = Math.max(...rows.map(([k]) => k.length));
-  const header = `${'Key'.padEnd(maxKey)}  Value`;
-  const divider = '-'.repeat(header.length);
-  console.log(header);
-  console.log(divider);
-  for (const [k, v] of rows) {
-    console.log(`${k.padEnd(maxKey)}  ${v}`);
-  }
-}
-
-export function registerConfigCommand(program: Command): void {
-  const cmd = program
-    .command('config')
-    .description('Manage Mosaic framework configuration')
-    .configureHelp({ sortSubcommands: true });
-
-  // ── config show ─────────────────────────────────────────────────────────
-
-  cmd
-    .command('show')
-    .description('Print the current resolved config')
-    .option('-f, --format <format>', 'Output format: table or json', 'table')
-    .action(async (opts: { format: string }) => {
-      const mosaicHome = getMosaicHome();
-      const svc = createConfigService(mosaicHome, mosaicHome);
-      assertInitialized(svc);
-
-      const config = await svc.readAll();
-
-      if (opts.format === 'json') {
-        console.log(JSON.stringify(config, null, 2));
-        return;
-      }
-
-      // Default: table
-      const rows = flattenConfig(config as unknown as Record<string, unknown>);
-      printTable(rows);
-    });
-
-  // ── config get <key> ────────────────────────────────────────────────────
-
-  cmd
-    .command('get <key>')
-    .description('Print a single config value (supports dotted keys, e.g. soul.agentName)')
-    .action(async (key: string) => {
-      const mosaicHome = getMosaicHome();
-      const svc = createConfigService(mosaicHome, mosaicHome);
-      assertInitialized(svc);
-
-      const value = await svc.getValue(key);
-      if (value === undefined) {
-        console.error(`Key "${key}" not found.`);
-        process.exit(1);
-      }
-      if (typeof value === 'object') {
-        console.log(JSON.stringify(value, null, 2));
-      } else {
-        console.log(String(value));
-      }
-    });
-
-  // ── config set <key> <value> ────────────────────────────────────────────
-
-  cmd
-    .command('set <key> <value>')
-    .description(
-      'Set a config value and persist (supports dotted keys, e.g. soul.agentName "Jarvis")',
-    )
-    .action(async (key: string, value: string) => {
-      const mosaicHome = getMosaicHome();
-      const svc = createConfigService(mosaicHome, mosaicHome);
-      assertInitialized(svc);
-
-      let previous: unknown;
-      try {
-        previous = await svc.setValue(key, value);
-      } catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-
-      const prevStr = previous === undefined ? '(unset)' : String(previous);
-      console.log(`${key}`);
-      console.log(`  old: ${prevStr}`);
-      console.log(`  new: ${value}`);
-    });
-
-  // ── config edit ─────────────────────────────────────────────────────────
-
-  cmd
-    .command('edit')
-    .description('Open the config directory in $EDITOR (or vi)')
-    .option('-s, --section <section>', 'Open a specific section file: soul | user | tools')
-    .action(async (opts: { section?: string }) => {
-      const mosaicHome = getMosaicHome();
-      const svc = createConfigService(mosaicHome, mosaicHome);
-      assertInitialized(svc);
-
-      const editor = process.env['EDITOR'] ?? 'vi';
-
-      let targetPath: string;
-      if (opts.section) {
-        const validSections = ['soul', 'user', 'tools'] as const;
-        if (!validSections.includes(opts.section as (typeof validSections)[number])) {
-          console.error(`Invalid section "${opts.section}". Choose: soul, user, tools`);
-          process.exit(1);
-        }
-        targetPath = svc.getConfigPath(opts.section as 'soul' | 'user' | 'tools');
-      } else {
-        targetPath = svc.getConfigPath();
-      }
-
-      const result = spawnSync(editor, [targetPath], { stdio: 'inherit' });
-
-      if (result.error) {
-        console.error(`Failed to open editor: ${result.error.message}`);
-        process.exit(1);
-      }
-
-      if (result.status !== 0) {
-        console.error(`Editor exited with code ${String(result.status ?? 1)}`);
-        process.exit(result.status ?? 1);
-      }
-
-      // Re-read after edit and report any issues
-      try {
-        await svc.readAll();
-        console.log('Config looks valid.');
-      } catch (err) {
-        console.error('Warning: config may have validation issues:');
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-    });
-
-  // ── config path ─────────────────────────────────────────────────────────
-
-  cmd
-    .command('path')
-    .description('Print the active config directory path (for scripting)')
-    .option(
-      '-s, --section <section>',
-      'Print path for a specific section file: soul | user | tools',
-    )
-    .action(async (opts: { section?: string }) => {
-      const mosaicHome = getMosaicHome();
-      const svc = createConfigService(mosaicHome, mosaicHome);
-
-      if (opts.section) {
-        const validSections = ['soul', 'user', 'tools'] as const;
-        if (!validSections.includes(opts.section as (typeof validSections)[number])) {
-          console.error(`Invalid section "${opts.section}". Choose: soul, user, tools`);
-          process.exit(1);
-        }
-        console.log(svc.getConfigPath(opts.section as 'soul' | 'user' | 'tools'));
-      } else {
-        console.log(svc.getConfigPath());
-      }
-    });
-}

packages/mosaic/src/config/config-service.ts

@@ -1,16 +1,6 @@
 import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
 import { FileConfigAdapter } from './file-adapter.js';
 
-/** Supported top-level config sections for dotted-key access. */
-export type ConfigSection = 'soul' | 'user' | 'tools';
-
-/** A resolved view of all config sections, keyed by section name. */
-export interface ResolvedConfig {
-  soul: SoulConfig;
-  user: UserConfig;
-  tools: ToolsConfig;
-}
-
 /**
  * ConfigService interface — abstracts config read/write operations.
  * Currently backed by FileConfigAdapter (writes .md files from templates).
@@ -26,35 +16,6 @@ export interface ConfigService {
   writeTools(config: ToolsConfig): Promise<void>;
 
   syncFramework(action: InstallAction): Promise<void>;
-
-  /**
-   * Return the resolved (merged) config across all sections.
-   */
-  readAll(): Promise<ResolvedConfig>;
-
-  /**
-   * Read a single value by dotted key (e.g. "soul.agentName").
-   * Returns undefined if the key doesn't exist.
-   */
-  getValue(dottedKey: string): Promise<unknown>;
-
-  /**
-   * Set a single value by dotted key (e.g. "soul.agentName") and persist.
-   * Returns the previous value (or undefined).
-   */
-  setValue(dottedKey: string, value: string): Promise<unknown>;
-
-  /**
-   * Return the filesystem path for a given config section file.
-   * When no section is provided, returns the mosaicHome directory.
-   */
-  getConfigPath(section?: ConfigSection): string;
-
-  /**
-   * Returns true if the mosaicHome directory exists and at least one
-   * config file (SOUL.md, USER.md, TOOLS.md) is present.
-   */
-  isInitialized(): boolean;
 }
 
 export function createConfigService(mosaicHome: string, sourceDir: string): ConfigService {

packages/mosaic/src/config/file-adapter.ts

@@ -1,6 +1,6 @@
 import { readFileSync, existsSync, readdirSync, statSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
-import type { ConfigService, ConfigSection, ResolvedConfig } from './config-service.js';
+import type { ConfigService } from './config-service.js';
 import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
 import { soulSchema, userSchema, toolsSchema } from './schemas.js';
 import { renderTemplate } from '../template/engine.js';
@@ -159,73 +159,6 @@ export class FileConfigAdapter implements ConfigService {
     }
   }
 
-  async readAll(): Promise<ResolvedConfig> {
-    const [soul, user, tools] = await Promise.all([
-      this.readSoul(),
-      this.readUser(),
-      this.readTools(),
-    ]);
-    return { soul, user, tools };
-  }
-
-  async getValue(dottedKey: string): Promise<unknown> {
-    const parts = dottedKey.split('.');
-    const section = parts[0] ?? '';
-    const field = parts.slice(1).join('.');
-    const config = await this.readAll();
-    if (!this.isValidSection(section)) return undefined;
-    const sectionData = config[section as ConfigSection] as Record<string, unknown>;
-    return field ? sectionData[field] : sectionData;
-  }
-
-  async setValue(dottedKey: string, value: string): Promise<unknown> {
-    const parts = dottedKey.split('.');
-    const section = parts[0] ?? '';
-    const field = parts.slice(1).join('.');
-    if (!this.isValidSection(section) || !field) {
-      throw new Error(
-        `Invalid key "${dottedKey}". Use format <section>.<field> (e.g. soul.agentName).`,
-      );
-    }
-
-    const previous = await this.getValue(dottedKey);
-
-    if (section === 'soul') {
-      const current = await this.readSoul();
-      await this.writeSoul({ ...current, [field]: value });
-    } else if (section === 'user') {
-      const current = await this.readUser();
-      await this.writeUser({ ...current, [field]: value });
-    } else {
-      const current = await this.readTools();
-      await this.writeTools({ ...current, [field]: value });
-    }
-
-    return previous;
-  }
-
-  getConfigPath(section?: ConfigSection): string {
-    if (!section) return this.mosaicHome;
-    const fileMap: Record<ConfigSection, string> = {
-      soul: join(this.mosaicHome, 'SOUL.md'),
-      user: join(this.mosaicHome, 'USER.md'),
-      tools: join(this.mosaicHome, 'TOOLS.md'),
-    };
-    return fileMap[section];
-  }
-
-  isInitialized(): boolean {
-    return (
-      existsSync(join(this.mosaicHome, 'SOUL.md')) ||
-      existsSync(join(this.mosaicHome, 'USER.md')) ||
-      existsSync(join(this.mosaicHome, 'TOOLS.md'))
-    );
-  }
-
-  private isValidSection(s: string): s is ConfigSection {
-    return s === 'soul' || s === 'user' || s === 'tools';
-  }
-
   /**
    * Look for template in source dir first, then mosaic home.
    */

packages/queue/package.json

@@ -22,6 +22,7 @@
   },
   "dependencies": {
     "@mosaicstack/types": "workspace:*",
+    "commander": "^13.0.0",
     "ioredis": "^5.10.0"
   },
   "devDependencies": {

packages/queue/src/cli.spec.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+import { registerQueueCommand } from './cli.js';
+
+describe('registerQueueCommand', () => {
+  function buildProgram(): Command {
+    const program = new Command('mosaic');
+    registerQueueCommand(program);
+    return program;
+  }
+
+  it('registers a "queue" subcommand', () => {
+    const program = buildProgram();
+    const queueCmd = program.commands.find((c) => c.name() === 'queue');
+    expect(queueCmd).toBeDefined();
+  });
+
+  it('queue has list, stats, pause, resume, jobs, drain subcommands', () => {
+    const program = buildProgram();
+    const queueCmd = program.commands.find((c) => c.name() === 'queue');
+    expect(queueCmd).toBeDefined();
+
+    const names = queueCmd!.commands.map((c) => c.name());
+    expect(names).toContain('list');
+    expect(names).toContain('stats');
+    expect(names).toContain('pause');
+    expect(names).toContain('resume');
+    expect(names).toContain('jobs');
+    expect(names).toContain('drain');
+  });
+
+  it('jobs subcommand has a "tail" subcommand', () => {
+    const program = buildProgram();
+    const queueCmd = program.commands.find((c) => c.name() === 'queue');
+    const jobsCmd = queueCmd!.commands.find((c) => c.name() === 'jobs');
+    expect(jobsCmd).toBeDefined();
+
+    const tailCmd = jobsCmd!.commands.find((c) => c.name() === 'tail');
+    expect(tailCmd).toBeDefined();
+  });
+
+  it('drain has a --yes option', () => {
+    const program = buildProgram();
+    const queueCmd = program.commands.find((c) => c.name() === 'queue');
+    const drainCmd = queueCmd!.commands.find((c) => c.name() === 'drain');
+    expect(drainCmd).toBeDefined();
+
+    const optionNames = drainCmd!.options.map((o) => o.long);
+    expect(optionNames).toContain('--yes');
+  });
+
+  it('stats accepts an optional [name] argument', () => {
+    const program = buildProgram();
+    const queueCmd = program.commands.find((c) => c.name() === 'queue');
+    const statsCmd = queueCmd!.commands.find((c) => c.name() === 'stats');
+    expect(statsCmd).toBeDefined();
+    // Should not throw when called without argument
+    const args = statsCmd!.registeredArguments;
+    expect(args.length).toBe(1);
+    expect(args[0]!.required).toBe(false);
+  });
+});

packages/queue/src/cli.ts

@@ -0,0 +1,248 @@
+import type { Command } from 'commander';
+
+import { createLocalAdapter } from './adapters/local.js';
+import type { QueueConfig } from './types.js';
+
+/** Resolve adapter type from env; defaults to 'local'. */
+function resolveAdapterType(): 'bullmq' | 'local' {
+  const t = process.env['QUEUE_ADAPTER'] ?? 'local';
+  return t === 'bullmq' ? 'bullmq' : 'local';
+}
+
+function resolveConfig(): QueueConfig {
+  const type = resolveAdapterType();
+  if (type === 'bullmq') {
+    return { type: 'bullmq', url: process.env['VALKEY_URL'] };
+  }
+  return { type: 'local', dataDir: process.env['QUEUE_DATA_DIR'] };
+}
+
+const BULLMQ_ONLY_MSG =
+  'not supported by local adapter — use the bullmq tier for this (set QUEUE_ADAPTER=bullmq)';
+
+/**
+ * Register queue subcommands on an existing Commander program.
+ * Follows the same pattern as registerQualityRails in @mosaicstack/quality-rails.
+ */
+export function registerQueueCommand(parent: Command): void {
+  buildQueueCommand(parent.command('queue').description('Manage Mosaic job queues'));
+}
+
+function buildQueueCommand(queue: Command): void {
+  // ─── list ──────────────────────────────────────────────────────────────
+  queue
+    .command('list')
+    .description('List all queues known to the configured adapter')
+    .action(async () => {
+      const config = resolveConfig();
+
+      if (config.type === 'local') {
+        const adapter = createLocalAdapter(config);
+        // Local adapter tracks queues in its internal Map; we expose them by
+        // listing JSON files in the data dir.
+        const { readdirSync } = await import('node:fs');
+        const { existsSync } = await import('node:fs');
+        const dataDir = config.dataDir ?? '.mosaic/queue';
+        if (!existsSync(dataDir)) {
+          console.log('No queues found (data dir does not exist yet).');
+          await adapter.close();
+          return;
+        }
+        const files = readdirSync(dataDir).filter((f: string) => f.endsWith('.json'));
+        if (files.length === 0) {
+          console.log('No queues found.');
+        } else {
+          console.log('Queues (local adapter):');
+          for (const f of files) {
+            console.log(`  - ${f.slice(0, -5)}`);
+          }
+        }
+        await adapter.close();
+        return;
+      }
+
+      // bullmq — not enough info to enumerate queues without a BullMQ Board
+      console.log(BULLMQ_ONLY_MSG);
+      process.exit(0);
+    });
+
+  // ─── stats ─────────────────────────────────────────────────────────────
+  queue
+    .command('stats [name]')
+    .description('Show stats for a queue (or all queues)')
+    .action(async (name?: string) => {
+      const config = resolveConfig();
+
+      if (config.type === 'local') {
+        const adapter = createLocalAdapter(config);
+        const { readdirSync } = await import('node:fs');
+        const { existsSync } = await import('node:fs');
+        const dataDir = config.dataDir ?? '.mosaic/queue';
+
+        let names: string[] = [];
+        if (name) {
+          names = [name];
+        } else {
+          if (existsSync(dataDir)) {
+            names = readdirSync(dataDir)
+              .filter((f: string) => f.endsWith('.json'))
+              .map((f: string) => f.slice(0, -5));
+          }
+        }
+
+        if (names.length === 0) {
+          console.log('No queues found.');
+          await adapter.close();
+          return;
+        }
+
+        for (const queueName of names) {
+          const len = await adapter.length(queueName);
+          console.log(`Queue: ${queueName}`);
+          console.log(`  waiting:   ${len}`);
+          console.log(`  active:    0 (local adapter — no active tracking)`);
+          console.log(`  completed: 0 (local adapter — no completed tracking)`);
+          console.log(`  failed:    0 (local adapter — no failed tracking)`);
+          console.log(`  delayed:   0 (local adapter — no delayed tracking)`);
+        }
+        await adapter.close();
+        return;
+      }
+
+      // bullmq
+      console.log(BULLMQ_ONLY_MSG);
+      process.exit(0);
+    });
+
+  // ─── pause ─────────────────────────────────────────────────────────────
+  queue
+    .command('pause <name>')
+    .description('Pause job processing for a queue')
+    .action(async (_name: string) => {
+      const config = resolveConfig();
+
+      if (config.type === 'local') {
+        console.log(BULLMQ_ONLY_MSG);
+        process.exit(0);
+        return;
+      }
+
+      console.log(BULLMQ_ONLY_MSG);
+      process.exit(0);
+    });
+
+  // ─── resume ────────────────────────────────────────────────────────────
+  queue
+    .command('resume <name>')
+    .description('Resume job processing for a queue')
+    .action(async (_name: string) => {
+      const config = resolveConfig();
+
+      if (config.type === 'local') {
+        console.log(BULLMQ_ONLY_MSG);
+        process.exit(0);
+        return;
+      }
+
+      console.log(BULLMQ_ONLY_MSG);
+      process.exit(0);
+    });
+
+  // ─── jobs tail ─────────────────────────────────────────────────────────
+  const jobs = queue.command('jobs').description('Job-level operations');
+
+  jobs
+    .command('tail [name]')
+    .description('Stream new jobs as they arrive (poll-based)')
+    .option('--interval <ms>', 'Poll interval in ms', '2000')
+    .action(async (name: string | undefined, opts: { interval: string }) => {
+      const config = resolveConfig();
+      const pollMs = parseInt(opts.interval, 10);
+
+      if (config.type === 'local') {
+        const adapter = createLocalAdapter(config);
+        const { existsSync, readdirSync } = await import('node:fs');
+        const dataDir = config.dataDir ?? '.mosaic/queue';
+
+        let names: string[] = [];
+        if (name) {
+          names = [name];
+        } else {
+          if (existsSync(dataDir)) {
+            names = readdirSync(dataDir)
+              .filter((f: string) => f.endsWith('.json'))
+              .map((f: string) => f.slice(0, -5));
+          }
+        }
+
+        if (names.length === 0) {
+          console.log('No queues to tail.');
+          await adapter.close();
+          return;
+        }
+
+        console.log(`Tailing queues: ${names.join(', ')} (Ctrl-C to stop)`);
+        const lastLen = new Map<string, number>();
+        for (const qn of names) {
+          lastLen.set(qn, await adapter.length(qn));
+        }
+
+        const timer = setInterval(async () => {
+          for (const qn of names) {
+            const len = await adapter.length(qn);
+            const prev = lastLen.get(qn) ?? 0;
+            if (len > prev) {
+              console.log(
+                `[${new Date().toISOString()}] ${qn}: ${len - prev} new job(s) (total: ${len})`,
+              );
+            }
+            lastLen.set(qn, len);
+          }
+        }, pollMs);
+
+        process.on('SIGINT', async () => {
+          clearInterval(timer);
+          await adapter.close();
+          process.exit(0);
+        });
+
+        return;
+      }
+
+      // bullmq — use subscribe on the channel
+      console.log(BULLMQ_ONLY_MSG);
+      process.exit(0);
+    });
+
+  // ─── drain ─────────────────────────────────────────────────────────────
+  queue
+    .command('drain <name>')
+    .description('Drain all pending jobs from a queue')
+    .option('--yes', 'Skip confirmation prompt')
+    .action(async (name: string, opts: { yes?: boolean }) => {
+      if (!opts.yes) {
+        console.error(
+          `WARNING: This will remove all pending jobs from queue "${name}". Re-run with --yes to confirm.`,
+        );
+        process.exit(1);
+        return;
+      }
+
+      const config = resolveConfig();
+
+      if (config.type === 'local') {
+        const adapter = createLocalAdapter(config);
+        let removed = 0;
+        while ((await adapter.length(name)) > 0) {
+          await adapter.dequeue(name);
+          removed++;
+        }
+        console.log(`Drained ${removed} job(s) from queue "${name}".`);
+        await adapter.close();
+        return;
+      }
+
+      console.log(BULLMQ_ONLY_MSG);
+      process.exit(0);
+    });
+}

packages/queue/src/index.ts

@@ -11,6 +11,7 @@ export { type QueueAdapter, type QueueConfig as QueueAdapterConfig } from './typ
 export { createQueueAdapter, registerQueueAdapter } from './factory.js';
 export { createBullMQAdapter } from './adapters/bullmq.js';
 export { createLocalAdapter } from './adapters/local.js';
+export { registerQueueCommand } from './cli.js';
 
 import { registerQueueAdapter } from './factory.js';
 import { createBullMQAdapter } from './adapters/bullmq.js';

pnpm-lock.yaml

@@ -441,6 +441,9 @@ importers:
       '@mosaicstack/types':
         specifier: workspace:*
         version: link:../types
+      commander:
+        specifier: ^13.0.0
+        version: 13.1.0
       drizzle-orm:
         specifier: ^0.45.1
         version: 0.45.1(@electric-sql/pglite@0.2.17)(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.15.6)(better-sqlite3@12.8.0)(kysely@0.28.11)(postgres@3.4.8)
@@ -469,12 +472,18 @@ importers:
       '@mosaicstack/macp':
         specifier: workspace:*
         version: link:../macp
+      '@mosaicstack/memory':
+        specifier: workspace:*
+        version: link:../memory
       '@mosaicstack/prdy':
         specifier: workspace:*
         version: link:../prdy
       '@mosaicstack/quality-rails':
         specifier: workspace:*
         version: link:../quality-rails
+      '@mosaicstack/queue':
+        specifier: workspace:*
+        version: link:../queue
       '@mosaicstack/types':
         specifier: workspace:*
         version: link:../types
@@ -571,6 +580,9 @@ importers:
       '@mosaicstack/types':
         specifier: workspace:*
         version: link:../types
+      commander:
+        specifier: ^13.0.0
+        version: 13.1.0
       ioredis:
         specifier: ^5.10.0
         version: 5.10.0