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/brain/package.json

@@ -22,8 +22,7 @@
   },
   "dependencies": {
     "@mosaicstack/db": "workspace:^",
-    "@mosaicstack/types": "workspace:*",
+    "@mosaicstack/types": "workspace:*"
-    "commander": "^13.0.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",

packages/brain/src/cli.spec.ts

@@ -1,95 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { Command } from 'commander';
-import { registerBrainCommand } from './cli.js';
-
-/**
- * Smoke test: verifies the command tree is correctly registered.
- * No database connection is opened — we only inspect Commander metadata.
- */
-describe('registerBrainCommand', () => {
-  function buildProgram(): Command {
-    const program = new Command('mosaic');
-    // Prevent Commander from calling process.exit on parse errors during tests.
-    program.exitOverride();
-    registerBrainCommand(program);
-    return program;
-  }
-
-  it('registers a top-level "brain" command', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain');
-    expect(brainCmd).toBeDefined();
-  });
-
-  it('registers "brain projects" with "list" and "create" subcommands', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const projectsCmd = brainCmd.commands.find((c) => c.name() === 'projects');
-    expect(projectsCmd).toBeDefined();
-
-    const subNames = projectsCmd!.commands.map((c) => c.name());
-    expect(subNames).toContain('list');
-    expect(subNames).toContain('create');
-  });
-
-  it('registers "brain missions" with "list" subcommand', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const missionsCmd = brainCmd.commands.find((c) => c.name() === 'missions');
-    expect(missionsCmd).toBeDefined();
-
-    const subNames = missionsCmd!.commands.map((c) => c.name());
-    expect(subNames).toContain('list');
-  });
-
-  it('registers "brain tasks" with "list" subcommand', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const tasksCmd = brainCmd.commands.find((c) => c.name() === 'tasks');
-    expect(tasksCmd).toBeDefined();
-
-    const subNames = tasksCmd!.commands.map((c) => c.name());
-    expect(subNames).toContain('list');
-  });
-
-  it('registers "brain conversations" with "list" subcommand', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const conversationsCmd = brainCmd.commands.find((c) => c.name() === 'conversations');
-    expect(conversationsCmd).toBeDefined();
-
-    const subNames = conversationsCmd!.commands.map((c) => c.name());
-    expect(subNames).toContain('list');
-  });
-
-  it('"brain projects list" accepts --db and --limit options', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const projectsCmd = brainCmd.commands.find((c) => c.name() === 'projects')!;
-    const listCmd = projectsCmd.commands.find((c) => c.name() === 'list')!;
-
-    const optionNames = listCmd.options.map((o) => o.long);
-    expect(optionNames).toContain('--db');
-    expect(optionNames).toContain('--limit');
-  });
-
-  it('"brain missions list" accepts --project option', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const missionsCmd = brainCmd.commands.find((c) => c.name() === 'missions')!;
-    const listCmd = missionsCmd.commands.find((c) => c.name() === 'list')!;
-
-    const optionNames = listCmd.options.map((o) => o.long);
-    expect(optionNames).toContain('--project');
-  });
-
-  it('"brain tasks list" accepts --project option', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const tasksCmd = brainCmd.commands.find((c) => c.name() === 'tasks')!;
-    const listCmd = tasksCmd.commands.find((c) => c.name() === 'list')!;
-
-    const optionNames = listCmd.options.map((o) => o.long);
-    expect(optionNames).toContain('--project');
-  });
-});

packages/brain/src/cli.ts

@@ -1,142 +0,0 @@
-import type { Command } from 'commander';
-import { createDb, type DbHandle } from '@mosaicstack/db';
-import { createBrain } from './brain.js';
-
-/**
- * Build and attach the `brain` subcommand tree onto an existing Commander program.
- * Uses the caller's Command instance to avoid cross-package Commander version mismatches.
- */
-export function registerBrainCommand(parent: Command): void {
-  const brain = parent.command('brain').description('Inspect and manage brain data stores');
-
-  // ─── shared DB option helper ─────────────────────────────────────────────
-
-  function addDbOption(cmd: Command): Command {
-    return cmd.option(
-      '--db <connection-string>',
-      'PostgreSQL connection string (overrides MOSAIC_DB_URL)',
-    );
-  }
-
-  function resolveDb(opts: { db?: string }): ReturnType<typeof createBrain> {
-    const connectionString = opts.db ?? process.env['MOSAIC_DB_URL'];
-    if (!connectionString) {
-      console.error('No DB connection string provided. Pass --db <url> or set MOSAIC_DB_URL.');
-      process.exit(1);
-    }
-    const handle: DbHandle = createDb(connectionString);
-    return createBrain(handle.db);
-  }
-
-  // ─── projects ────────────────────────────────────────────────────────────
-
-  const projects = brain.command('projects').description('Manage projects');
-
-  addDbOption(
-    projects
-      .command('list')
-      .description('List all projects')
-      .option('--limit <n>', 'Maximum number of results', '50'),
-  ).action(async (opts: { db?: string; limit: string }) => {
-    const b = resolveDb(opts);
-    const limit = parseInt(opts.limit, 10);
-    const rows = await b.projects.findAll();
-    const sliced = rows.slice(0, limit);
-    if (sliced.length === 0) {
-      console.log('No projects found.');
-      return;
-    }
-    for (const p of sliced) {
-      console.log(`${p.id}  ${p.name}`);
-    }
-  });
-
-  addDbOption(
-    projects
-      .command('create <name>')
-      .description('Create a new project')
-      .requiredOption('--owner-id <id>', 'Owner user ID'),
-  ).action(async (name: string, opts: { db?: string; ownerId: string }) => {
-    const b = resolveDb(opts);
-    const created = await b.projects.create({
-      name,
-      ownerId: opts.ownerId,
-      ownerType: 'user',
-    });
-    console.log(`Created project: ${created.id}  ${created.name}`);
-  });
-
-  // ─── missions ────────────────────────────────────────────────────────────
-
-  const missions = brain.command('missions').description('Manage missions');
-
-  addDbOption(
-    missions
-      .command('list')
-      .description('List all missions')
-      .option('--limit <n>', 'Maximum number of results', '50')
-      .option('--project <id>', 'Filter by project ID'),
-  ).action(async (opts: { db?: string; limit: string; project?: string }) => {
-    const b = resolveDb(opts);
-    const limit = parseInt(opts.limit, 10);
-    const rows = opts.project
-      ? await b.missions.findByProject(opts.project)
-      : await b.missions.findAll();
-    const sliced = rows.slice(0, limit);
-    if (sliced.length === 0) {
-      console.log('No missions found.');
-      return;
-    }
-    for (const m of sliced) {
-      console.log(`${m.id}  ${m.name}`);
-    }
-  });
-
-  // ─── tasks ────────────────────────────────────────────────────────────────
-
-  const tasks = brain.command('tasks').description('Manage generic tasks');
-
-  addDbOption(
-    tasks
-      .command('list')
-      .description('List all tasks')
-      .option('--limit <n>', 'Maximum number of results', '50')
-      .option('--project <id>', 'Filter by project ID'),
-  ).action(async (opts: { db?: string; limit: string; project?: string }) => {
-    const b = resolveDb(opts);
-    const limit = parseInt(opts.limit, 10);
-    const rows = opts.project ? await b.tasks.findByProject(opts.project) : await b.tasks.findAll();
-    const sliced = rows.slice(0, limit);
-    if (sliced.length === 0) {
-      console.log('No tasks found.');
-      return;
-    }
-    for (const t of sliced) {
-      console.log(`${t.id}  ${t.title}  [${t.status}]`);
-    }
-  });
-
-  // ─── conversations ────────────────────────────────────────────────────────
-
-  const conversations = brain.command('conversations').description('Manage conversations');
-
-  addDbOption(
-    conversations
-      .command('list')
-      .description('List conversations for a user')
-      .option('--limit <n>', 'Maximum number of results', '50')
-      .requiredOption('--user-id <id>', 'User ID to scope the query'),
-  ).action(async (opts: { db?: string; limit: string; userId: string }) => {
-    const b = resolveDb(opts);
-    const limit = parseInt(opts.limit, 10);
-    const rows = await b.conversations.findAll(opts.userId);
-    const sliced = rows.slice(0, limit);
-    if (sliced.length === 0) {
-      console.log('No conversations found.');
-      return;
-    }
-    for (const c of sliced) {
-      console.log(`${c.id}  ${c.title ?? '(untitled)'}`);
-    }
-  });
-}

packages/brain/src/index.ts

@@ -1,5 +1,4 @@
 export { createBrain, type Brain } from './brain.js';
-export { registerBrainCommand } from './cli.js';
 export {
   createProjectsRepo,
   type ProjectsRepo,

packages/mosaic/package.json

@@ -27,7 +27,6 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@mosaicstack/brain": "workspace:*",
     "@mosaicstack/config": "workspace:*",
     "@mosaicstack/forge": "workspace:*",
     "@mosaicstack/macp": "workspace:*",

packages/mosaic/src/cli.ts

@@ -2,7 +2,6 @@
 
 import { createRequire } from 'module';
 import { Command } from 'commander';
-import { registerBrainCommand } from '@mosaicstack/brain';
 import { registerQualityRails } from '@mosaicstack/quality-rails';
 import { registerAgentCommand } from './commands/agent.js';
 import { registerMissionCommand } from './commands/mission.js';
@@ -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')
@@ -315,10 +333,6 @@ registerAgentCommand(program);
 
 registerMissionCommand(program);
 
-// ─── brain ──────────────────────────────────────────────────────────────
-
-registerBrainCommand(program);
-
 // ─── quality-rails ──────────────────────────────────────────────────────
 
 registerQualityRails(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,

pnpm-lock.yaml

@@ -294,9 +294,6 @@ importers:
       '@mosaicstack/types':
         specifier: workspace:*
         version: link:../types
-      commander:
-        specifier: ^13.0.0
-        version: 13.1.0
     devDependencies:
       typescript:
         specifier: ^5.8.0
@@ -457,9 +454,6 @@ importers:
       '@clack/prompts':
         specifier: ^0.9.1
         version: 0.9.1
-      '@mosaicstack/brain':
-        specifier: workspace:*
-        version: link:../brain
       '@mosaicstack/config':
         specifier: workspace:*
         version: link:../config