feat(mosaic): alphabetize and group mosaic --help output

Enables sortSubcommands on the root program, sessions group, gateway
group, and mission group so all subcommand listings render A-Z. Appends
a Command Groups section via addHelpText to group commands by role
(Runtime, Gateway, Framework, Platform, Runtimes).

Implements CU-04-01, CU-04-02, CU-04-03 from mission cli-unification-20260404.

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

packages/mosaic/package.json

@@ -32,7 +32,6 @@
     "@mosaicstack/macp": "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,7 +3,6 @@
 import { createRequire } from 'module';
 import { Command } from 'commander';
 import { registerQualityRails } from '@mosaicstack/quality-rails';
-import { registerQueueCommand } from '@mosaicstack/queue';
 import { registerAgentCommand } from './commands/agent.js';
 import { registerMissionCommand } from './commands/mission.js';
 // prdy is registered via launch.ts
@@ -34,7 +33,23 @@ try {
 
 const program = new Command();
 
-program.name('mosaic').description('Mosaic Stack CLI').version(CLI_VERSION);
+program
+  .name('mosaic')
+  .description('Mosaic Stack CLI')
+  .version(CLI_VERSION)
+  .configureHelp({ sortSubcommands: true })
+  .addHelpText(
+    'after',
+    `
+Command Groups:
+
+  Runtime:    tui, login, sessions
+  Gateway:    gateway
+  Framework:  agent, bootstrap, coord, doctor, init, launch, mission, prdy, seq, sync, upgrade, wizard, yolo
+  Platform:   update
+  Runtimes:   claude, codex, opencode, pi
+`,
+  );
 
 // ─── runtime launchers + framework commands ────────────────────────────
 
@@ -215,7 +230,10 @@ program
 
 // ─── sessions ───────────────────────────────────────────────────────────
 
-const sessionsCmd = program.command('sessions').description('Manage active agent sessions');
+const sessionsCmd = program
+  .command('sessions')
+  .description('Manage active agent sessions')
+  .configureHelp({ sortSubcommands: true });
 
 sessionsCmd
   .command('list')
@@ -319,10 +337,6 @@ registerMissionCommand(program);
 
 registerQualityRails(program);
 
-// ─── queue ───────────────────────────────────────────────────────────────
-
-registerQueueCommand(program);
-
 // ─── update ─────────────────────────────────────────────────────────────
 
 program

packages/mosaic/src/commands/gateway.ts

@@ -30,6 +30,7 @@ export function registerGatewayCommand(program: Command): void {
     .option('-h, --host <host>', 'Gateway host', 'localhost')
     .option('-p, --port <port>', 'Gateway port', '14242')
     .option('-t, --token <token>', 'Admin API token')
+    .configureHelp({ sortSubcommands: true })
     .action(() => {
       gw.outputHelp();
     });

packages/mosaic/src/commands/mission.ts

@@ -47,6 +47,7 @@ export function registerMissionCommand(program: Command) {
     .option('--update <idOrName>', 'Update a mission')
     .option('--project <idOrName>', 'Scope to project')
     .argument('[id]', 'Show mission detail by ID')
+    .configureHelp({ sortSubcommands: true })
     .action(
       async (
         id: string | undefined,

packages/queue/package.json

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

packages/queue/src/cli.spec.ts

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

@@ -1,248 +0,0 @@
-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,7 +11,6 @@ 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

@@ -469,9 +469,6 @@ importers:
       '@mosaicstack/quality-rails':
         specifier: workspace:*
         version: link:../quality-rails
-      '@mosaicstack/queue':
-        specifier: workspace:*
-        version: link:../queue
       '@mosaicstack/types':
         specifier: workspace:*
         version: link:../types
@@ -568,9 +565,6 @@ 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