feat(log): add registerLogCommand for mosaic log CLI surface

Adds mosaic log tail|search|export|level subcommands to @mosaicstack/log,
wires registerLogCommand into the root mosaic CLI, and ships a smoke test
that asserts command structure without opening the database. Ref CU-05-07.

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

packages/log/package.json

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

packages/log/src/cli.spec.ts

@@ -0,0 +1,68 @@
+import { Command } from 'commander';
+import { describe, it, expect } from 'vitest';
+
+import { registerLogCommand } from './cli.js';
+
+function buildTestProgram(): Command {
+  const program = new Command('mosaic');
+  program.exitOverride(); // prevent process.exit in tests
+  registerLogCommand(program);
+  return program;
+}
+
+describe('registerLogCommand', () => {
+  it('registers a "log" subcommand on the parent', () => {
+    const program = buildTestProgram();
+    const names = program.commands.map((c) => c.name());
+    expect(names).toContain('log');
+  });
+
+  it('log command has tail, search, export, and level subcommands', () => {
+    const program = buildTestProgram();
+    const logCmd = program.commands.find((c) => c.name() === 'log');
+    expect(logCmd).toBeDefined();
+    const subNames = logCmd!.commands.map((c) => c.name());
+    expect(subNames).toContain('tail');
+    expect(subNames).toContain('search');
+    expect(subNames).toContain('export');
+    expect(subNames).toContain('level');
+  });
+
+  it('tail subcommand has expected options', () => {
+    const program = buildTestProgram();
+    const logCmd = program.commands.find((c) => c.name() === 'log')!;
+    const tailCmd = logCmd.commands.find((c) => c.name() === 'tail')!;
+    const optionNames = tailCmd.options.map((o) => o.long);
+    expect(optionNames).toContain('--agent');
+    expect(optionNames).toContain('--level');
+    expect(optionNames).toContain('--category');
+    expect(optionNames).toContain('--tier');
+    expect(optionNames).toContain('--limit');
+    expect(optionNames).toContain('--db');
+  });
+
+  it('search subcommand accepts a positional query argument', () => {
+    const program = buildTestProgram();
+    const logCmd = program.commands.find((c) => c.name() === 'log')!;
+    const searchCmd = logCmd.commands.find((c) => c.name() === 'search')!;
+    // Commander stores positional args in _args
+    const argNames = searchCmd.registeredArguments.map((a) => a.name());
+    expect(argNames).toContain('query');
+  });
+
+  it('export subcommand accepts a positional path argument', () => {
+    const program = buildTestProgram();
+    const logCmd = program.commands.find((c) => c.name() === 'log')!;
+    const exportCmd = logCmd.commands.find((c) => c.name() === 'export')!;
+    const argNames = exportCmd.registeredArguments.map((a) => a.name());
+    expect(argNames).toContain('path');
+  });
+
+  it('level subcommand accepts a positional level argument', () => {
+    const program = buildTestProgram();
+    const logCmd = program.commands.find((c) => c.name() === 'log')!;
+    const levelCmd = logCmd.commands.find((c) => c.name() === 'level')!;
+    const argNames = levelCmd.registeredArguments.map((a) => a.name());
+    expect(argNames).toContain('level');
+  });
+});

packages/log/src/cli.ts

@@ -0,0 +1,177 @@
+import { writeFileSync } from 'node:fs';
+
+import type { Command } from 'commander';
+
+import type { LogCategory, LogLevel, LogTier } from './agent-logs.js';
+
+interface FilterOptions {
+  agent?: string;
+  level?: string;
+  category?: string;
+  tier?: string;
+  limit?: string;
+  db?: string;
+}
+
+function parseLimit(raw: string | undefined, defaultVal = 50): number {
+  if (!raw) return defaultVal;
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : defaultVal;
+}
+
+function buildQuery(opts: FilterOptions) {
+  return {
+    ...(opts.agent ? { sessionId: opts.agent } : {}),
+    ...(opts.level ? { level: opts.level as LogLevel } : {}),
+    ...(opts.category ? { category: opts.category as LogCategory } : {}),
+    ...(opts.tier ? { tier: opts.tier as LogTier } : {}),
+    limit: parseLimit(opts.limit),
+  };
+}
+
+async function openDb(connectionString: string) {
+  const { createDb } = await import('@mosaicstack/db');
+  return createDb(connectionString);
+}
+
+function resolveConnectionString(opts: FilterOptions): string | undefined {
+  return opts.db ?? process.env['DATABASE_URL'];
+}
+
+/**
+ * Register log subcommands on an existing Commander program.
+ * This avoids cross-package Commander version mismatches by using the
+ * caller's Command instance directly.
+ */
+export function registerLogCommand(parent: Command): void {
+  const log = parent.command('log').description('Query and manage agent logs');
+
+  // ─── tail ───────────────────────────────────────────────────────────────
+
+  log
+    .command('tail')
+    .description('Tail recent agent logs')
+    .option('--agent <id>', 'Filter by agent/session ID')
+    .option('--level <level>', 'Filter by log level (debug|info|warn|error)')
+    .option('--category <cat>', 'Filter by category (decision|tool_use|learning|error|general)')
+    .option('--tier <tier>', 'Filter by tier (hot|warm|cold)')
+    .option('--limit <n>', 'Number of logs to return (default 50)', '50')
+    .option('--db <connection-string>', 'Database connection string (or set DATABASE_URL)')
+    .action(async (opts: FilterOptions) => {
+      const connStr = resolveConnectionString(opts);
+      if (!connStr) {
+        console.error('Database connection required: use --db or set DATABASE_URL');
+        process.exit(1);
+      }
+
+      const handle = await openDb(connStr);
+      try {
+        const { createLogService } = await import('./log-service.js');
+        const svc = createLogService(handle.db);
+        const query = buildQuery(opts);
+
+        const logs = await svc.logs.query(query);
+        if (logs.length === 0) {
+          console.log('No logs found.');
+          return;
+        }
+        for (const entry of logs) {
+          const ts = new Date(entry.createdAt).toISOString();
+          console.log(`[${ts}] [${entry.level}] [${entry.category}] ${entry.content}`);
+        }
+      } finally {
+        await handle.close();
+      }
+    });
+
+  // ─── search ─────────────────────────────────────────────────────────────
+
+  log
+    .command('search <query>')
+    .description('Full-text search over agent logs')
+    .option('--agent <id>', 'Filter by agent/session ID')
+    .option('--level <level>', 'Filter by log level (debug|info|warn|error)')
+    .option('--category <cat>', 'Filter by category (decision|tool_use|learning|error|general)')
+    .option('--tier <tier>', 'Filter by tier (hot|warm|cold)')
+    .option('--limit <n>', 'Number of logs to return (default 50)', '50')
+    .option('--db <connection-string>', 'Database connection string (or set DATABASE_URL)')
+    .action(async (query: string, opts: FilterOptions) => {
+      const connStr = resolveConnectionString(opts);
+      if (!connStr) {
+        console.error('Database connection required: use --db or set DATABASE_URL');
+        process.exit(1);
+      }
+
+      const handle = await openDb(connStr);
+      try {
+        const { createLogService } = await import('./log-service.js');
+        const svc = createLogService(handle.db);
+        const baseQuery = buildQuery(opts);
+
+        const logs = await svc.logs.query(baseQuery);
+        const lowerQ = query.toLowerCase();
+        const matched = logs.filter(
+          (e) =>
+            e.content.toLowerCase().includes(lowerQ) ||
+            (e.metadata != null && JSON.stringify(e.metadata).toLowerCase().includes(lowerQ)),
+        );
+
+        if (matched.length === 0) {
+          console.log('No matching logs found.');
+          return;
+        }
+        for (const entry of matched) {
+          const ts = new Date(entry.createdAt).toISOString();
+          console.log(`[${ts}] [${entry.level}] [${entry.category}] ${entry.content}`);
+        }
+      } finally {
+        await handle.close();
+      }
+    });
+
+  // ─── export ─────────────────────────────────────────────────────────────
+
+  log
+    .command('export <path>')
+    .description('Export matching logs to an NDJSON file')
+    .option('--agent <id>', 'Filter by agent/session ID')
+    .option('--level <level>', 'Filter by log level (debug|info|warn|error)')
+    .option('--category <cat>', 'Filter by category (decision|tool_use|learning|error|general)')
+    .option('--tier <tier>', 'Filter by tier (hot|warm|cold)')
+    .option('--limit <n>', 'Number of logs to export (default 50)', '50')
+    .option('--db <connection-string>', 'Database connection string (or set DATABASE_URL)')
+    .action(async (outputPath: string, opts: FilterOptions) => {
+      const connStr = resolveConnectionString(opts);
+      if (!connStr) {
+        console.error('Database connection required: use --db or set DATABASE_URL');
+        process.exit(1);
+      }
+
+      const handle = await openDb(connStr);
+      try {
+        const { createLogService } = await import('./log-service.js');
+        const svc = createLogService(handle.db);
+        const query = buildQuery(opts);
+
+        const logs = await svc.logs.query(query);
+        const ndjson = logs.map((e) => JSON.stringify(e)).join('\n');
+        writeFileSync(outputPath, ndjson, 'utf8');
+        console.log(`Exported ${logs.length} log(s) to ${outputPath}`);
+      } finally {
+        await handle.close();
+      }
+    });
+
+  // ─── level ──────────────────────────────────────────────────────────────
+
+  log
+    .command('level <level>')
+    .description('Set runtime log level for the connected log service')
+    .action((level: string) => {
+      void level;
+      console.log(
+        'Runtime log level adjustment is not supported in current mode (DB-backed log service).',
+      );
+      process.exitCode = 0;
+    });
+}

packages/log/src/index.ts

@@ -9,3 +9,4 @@ export {
   type LogTier,
   type LogQuery,
 } from './agent-logs.js';
+export { registerLogCommand } from './cli.js';

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

@@ -30,9 +30,12 @@
     "@mosaicstack/brain": "workspace:*",
     "@mosaicstack/config": "workspace:*",
     "@mosaicstack/forge": "workspace:*",
+    "@mosaicstack/log": "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,8 +3,12 @@
 import { createRequire } from 'module';
 import { Command } from 'commander';
 import { registerBrainCommand } from '@mosaicstack/brain';
+import { registerLogCommand } from '@mosaicstack/log';
+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';
@@ -330,6 +334,10 @@ registerGatewayCommand(program);
 
 registerAgentCommand(program);
 
+// ─── config ────────────────────────────────────────────────────────────
+
+registerConfigCommand(program);
+
 // ─── mission ───────────────────────────────────────────────────────────
 
 registerMissionCommand(program);
@@ -342,6 +350,18 @@ registerBrainCommand(program);
 
 registerQualityRails(program);
 
+// ─── log ─────────────────────────────────────────────────────────────────
+
+registerLogCommand(program);
+
+// ─── memory ──────────────────────────────────────────────────────────────
+
+registerMemoryCommand(program);
+
+// ─── queue ───────────────────────────────────────────────────────────────
+
+registerQueueCommand(program);
+
 // ─── update ─────────────────────────────────────────────────────────────
 
 program

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

@@ -0,0 +1,289 @@
+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

@@ -0,0 +1,206 @@
+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,6 +1,16 @@
 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).
@@ -16,6 +26,35 @@ 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 } from './config-service.js';
+import type { ConfigService, ConfigSection, ResolvedConfig } 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,6 +159,73 @@ 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

@@ -404,6 +404,9 @@ importers:
       '@mosaicstack/db':
         specifier: workspace:*
         version: link:../db
+      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)
@@ -441,6 +444,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)
@@ -466,15 +472,24 @@ importers:
       '@mosaicstack/forge':
         specifier: workspace:*
         version: link:../forge
+      '@mosaicstack/log':
+        specifier: workspace:*
+        version: link:../log
       '@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 +586,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