@nemus-cli/nemus 0.2.12 → 0.2.13

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.13] - 2026-08-27
+
+### Added
+
+- **Shell completions**: `nemus completion bash|zsh|fish` prints a completion
+  script for that shell. Completes subcommands (names + aliases) and, for a
+  workspace-scoped command, live **workspace names** — the script calls back
+  into `nemus completion --workspaces`, so completions stay fresh without
+  regenerating. Registered for both the `nemus` and `nem` binaries. Install e.g.
+  `nemus completion zsh > "${fpath[1]}/_nemus"` (see README).
+
 ## [0.2.12] - 2026-08-27
 
 ### Added

package/README.md

@@ -243,6 +243,24 @@ The workspace-scoped ones (`status`/`doctor`/`analyze-deps`) need an explicit
 workspace name with `--json` (they never prompt). On failure, `--json` prints a
 parseable `{ "ok": false, "error": … }` to stdout and exits non-zero.
 
+### Shell completions
+
+Tab-complete subcommands and workspace names. `nemus completion <shell>` prints
+a script for `bash`, `zsh`, or `fish` (works for both the `nemus` and `nem`
+binaries):
+
+```bash
+# bash
+nemus completion bash > /etc/bash_completion.d/nemus     # or >> ~/.bashrc
+# zsh (a directory on your $fpath)
+nemus completion zsh > "${fpath[1]}/_nemus"
+# fish
+nemus completion fish > ~/.config/fish/completions/nemus.fish
+```
+
+Workspace names are resolved live (the script calls back into the CLI), so they
+stay current without regenerating.
+
 ### Suites (reusable repo collections)
 
 ```bash

package/dist/commands/completion.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPLETION_BINS = void 0;
+exports.generateCompletion = generateCompletion;
+exports.specsFromProgram = specsFromProgram;
+exports.registerCompletionCommand = registerCompletionCommand;
+const workspace_meta_1 = require("../utils/workspace-meta");
+const logger_1 = require("../utils/logger");
+/** Binaries that get completion registered (the CLI's bins). */
+exports.COMPLETION_BINS = ['nemus', 'nem'];
+/** Every token (name + aliases) that should complete as a subcommand. */
+function allTokens(cmds) {
+    return cmds.flatMap((c) => [c.name, ...c.aliases]);
+}
+/** Tokens (names + aliases) of the commands that take a workspace argument. */
+function workspaceTokens(cmds) {
+    return cmds.filter((c) => c.takesWorkspace).flatMap((c) => [c.name, ...c.aliases]);
+}
+/** Escape a description for a fish single-quoted string. */
+function fishDesc(s) {
+    return s.replace(/\n/g, ' ').replace(/'/g, "'\\''");
+}
+/**
+ * Generate a shell completion script. Pure (no I/O) so it's unit-tested. The
+ * generated script completes subcommands at position 1, and for a subcommand
+ * that takes a workspace it completes workspace names by calling back into the
+ * CLI: `<bin> completion --workspaces`. Dynamic values stay fresh without
+ * regenerating the script.
+ */
+function generateCompletion(shell, cmds, bins = exports.COMPLETION_BINS) {
+    const commands = allTokens(cmds).join(' ');
+    const wsCommands = workspaceTokens(cmds).join(' ');
+    if (shell === 'bash') {
+        return `# nemus bash completion. Install: nemus completion bash > /etc/bash_completion.d/nemus
+#   (or: nemus completion bash >> ~/.bashrc)
+_nemus_complete() {
+  local cur bin sub
+  # bash does not clear COMPREPLY between completions; reset so a stale result
+  # from a previous TAB can't leak when we return without setting it.
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  bin="\${COMP_WORDS[0]}"
+  local commands="${commands}"
+  local ws_commands="${wsCommands}"
+  if [ "\$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( \$(compgen -W "\$commands" -- "\$cur") )
+    return 0
+  fi
+  if [ "\$COMP_CWORD" -eq 2 ]; then
+    sub="\${COMP_WORDS[1]}"
+    if [[ " \$ws_commands " == *" \$sub "* ]]; then
+      local names
+      names="\$("\$bin" completion --workspaces 2>/dev/null)"
+      COMPREPLY=( \$(compgen -W "\$names" -- "\$cur") )
+      return 0
+    fi
+  fi
+  return 0
+}
+${bins.map((b) => `complete -F _nemus_complete ${b}`).join('\n')}
+`;
+    }
+    if (shell === 'zsh') {
+        // Autoloaded form: save as a file named `_nemus` on your $fpath.
+        return `#compdef ${bins.join(' ')}
+# nemus zsh completion. Install: nemus completion zsh > "\${fpath[1]}/_nemus"
+local -a _nemus_commands
+_nemus_commands=(${allTokens(cmds).map((t) => `'${t}'`).join(' ')})
+local _nemus_ws_commands="${wsCommands}"
+if (( CURRENT == 2 )); then
+  compadd -- $_nemus_commands
+  return
+fi
+if (( CURRENT == 3 )); then
+  local sub=\${words[2]}
+  if [[ " $_nemus_ws_commands " == *" $sub "* ]]; then
+    local -a _nemus_names
+    _nemus_names=(\${(f)"$(\${words[1]} completion --workspaces 2>/dev/null)"})
+    compadd -- $_nemus_names
+  fi
+fi
+`;
+    }
+    // fish
+    const lines = ['# nemus fish completion. Install: nemus completion fish > ~/.config/fish/completions/nemus.fish'];
+    for (const bin of bins) {
+        lines.push(`complete -c ${bin} -f`);
+        for (const c of cmds) {
+            for (const tok of [c.name, ...c.aliases]) {
+                lines.push(`complete -c ${bin} -n __fish_use_subcommand -a '${tok}' -d '${fishDesc(c.description)}'`);
+            }
+        }
+        const wsToks = workspaceTokens(cmds).join(' ');
+        if (wsToks) {
+            lines.push(`complete -c ${bin} -n '__fish_seen_subcommand_from ${wsToks}' -a '(${bin} completion --workspaces)'`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+/** Distill the program's top-level commands into CommandSpecs. */
+function specsFromProgram(program) {
+    return program.commands
+        .map((c) => {
+        const args = c.registeredArguments ?? [];
+        const firstArg = args[0]?.name?.();
+        return {
+            name: c.name(),
+            aliases: c.aliases(),
+            takesWorkspace: typeof firstArg === 'string' && firstArg.toLowerCase().includes('workspace'),
+            description: c.description() ?? '',
+        };
+    })
+        // The completion command itself and any hidden helper needn't clutter, but
+        // keeping them is harmless; only drop entries with no name.
+        .filter((s) => s.name);
+}
+function registerCompletionCommand(program) {
+    program
+        .command('completion [shell]')
+        .description('Output a shell completion script (bash|zsh|fish)')
+        .option('--workspaces', 'Print workspace names (used internally by completion scripts)')
+        .action(async (shell, opts) => {
+        // Data helper the generated scripts call back into.
+        if (opts.workspaces) {
+            try {
+                const workspaces = await (0, workspace_meta_1.listWorkspaces)(false);
+                for (const ws of workspaces)
+                    process.stdout.write(ws.name + '\n');
+            }
+            catch {
+                // Silent: completion must never error out the user's shell.
+            }
+            return;
+        }
+        const shells = ['bash', 'zsh', 'fish'];
+        if (!shell || !shells.includes(shell)) {
+            (0, logger_1.logError)(`completion: specify a shell — one of ${shells.join(', ')}`);
+            (0, logger_1.logError)('e.g. nemus completion bash');
+            process.exit(1);
+        }
+        process.stdout.write(generateCompletion(shell, specsFromProgram(program)));
+    });
+}

package/dist/program.js

@@ -88,6 +88,7 @@ const ghq_status_1 = require("./commands/ghq-status");
 const save_context_1 = require("./commands/save-context");
 const migrate_1 = require("./commands/migrate");
 const report_bug_1 = require("./commands/report-bug");
+const completion_1 = require("./commands/completion");
 (0, create_1.registerCreateCommand)(exports.program);
 (0, list_1.registerListCommand)(exports.program);
 (0, update_1.registerUpdateCommand)(exports.program);
@@ -111,6 +112,7 @@ const report_bug_1 = require("./commands/report-bug");
 (0, save_context_1.registerSaveContextCommand)(exports.program);
 (0, migrate_1.registerMigrateCommand)(exports.program);
 (0, report_bug_1.registerReportBugCommand)(exports.program);
+(0, completion_1.registerCompletionCommand)(exports.program);
 // Register TUI (delegates to existing Ink/React implementation)
 exports.program
     .command('tui')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "workspaces": [
     "packages/*"
   ],

package/src/commands/completion.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+import { generateCompletion, specsFromProgram, CommandSpec } from './completion';
+
+const specs: CommandSpec[] = [
+  { name: 'list', aliases: ['l'], takesWorkspace: false, description: 'List workspaces' },
+  { name: 'status', aliases: ['st'], takesWorkspace: true, description: "Show a repo's git status" },
+  { name: 'doctor', aliases: ['doc'], takesWorkspace: true, description: 'Health checks' },
+];
+
+describe('generateCompletion — bash', () => {
+  const s = generateCompletion('bash', specs);
+  it('resets COMPREPLY, lists tokens, and registers both bins', () => {
+    expect(s).toContain('COMPREPLY=()'); // guards the stale-completion leak
+    expect(s).toContain('local commands="list l status st doctor doc"');
+    expect(s).toContain('local ws_commands="status st doctor doc"');
+    expect(s).toContain('complete -F _nemus_complete nemus');
+    expect(s).toContain('complete -F _nemus_complete nem');
+  });
+  it('calls back into the invoked bin for workspace names', () => {
+    expect(s).toContain('"$bin" completion --workspaces');
+  });
+});
+
+describe('generateCompletion — zsh', () => {
+  const s = generateCompletion('zsh', specs);
+  it('is an autoloadable #compdef script with the tokens + callback', () => {
+    expect(s.startsWith('#compdef nemus nem')).toBe(true);
+    expect(s).toContain("_nemus_commands=('list' 'l' 'status' 'st' 'doctor' 'doc')");
+    expect(s).toContain('_nemus_ws_commands="status st doctor doc"');
+    expect(s).toContain('completion --workspaces');
+  });
+});
+
+describe('generateCompletion — fish', () => {
+  const s = generateCompletion('fish', specs);
+  it('emits subcommand + workspace completions for both bins with escaped descriptions', () => {
+    expect(s).toContain("complete -c nemus -n __fish_use_subcommand -a 'list' -d 'List workspaces'");
+    expect(s).toContain("complete -c nem -n __fish_use_subcommand -a 'status'");
+    // apostrophe in the description is escaped for fish's single-quoted string
+    expect(s).toContain("Show a repo'\\''s git status");
+    expect(s).toContain("-n '__fish_seen_subcommand_from status st doctor doc' -a '(nemus completion --workspaces)'");
+  });
+});
+
+describe('specsFromProgram', () => {
+  it('detects workspace args + aliases from a commander program', () => {
+    const program = new Command();
+    program.command('list').alias('l').description('list');
+    program.command('status [workspace]').alias('st').description('status');
+    program.command('create').description('create');
+
+    const out = specsFromProgram(program);
+    const byName = Object.fromEntries(out.map((s) => [s.name, s]));
+    expect(byName.status.takesWorkspace).toBe(true);
+    expect(byName.status.aliases).toEqual(['st']);
+    expect(byName.list.takesWorkspace).toBe(false);
+    expect(byName.create.takesWorkspace).toBe(false);
+  });
+});

package/src/commands/completion.ts

@@ -0,0 +1,160 @@
+import { Command } from 'commander';
+import { listWorkspaces } from '../utils/workspace-meta';
+import { logError } from '../utils/logger';
+
+/** Binaries that get completion registered (the CLI's bins). */
+export const COMPLETION_BINS = ['nemus', 'nem'];
+
+export type Shell = 'bash' | 'zsh' | 'fish';
+
+/** One top-level command, distilled to what a completion script needs. */
+export interface CommandSpec {
+  name: string;
+  aliases: string[];
+  /** True if its first positional argument is a workspace name. */
+  takesWorkspace: boolean;
+  description: string;
+}
+
+/** Every token (name + aliases) that should complete as a subcommand. */
+function allTokens(cmds: CommandSpec[]): string[] {
+  return cmds.flatMap((c) => [c.name, ...c.aliases]);
+}
+
+/** Tokens (names + aliases) of the commands that take a workspace argument. */
+function workspaceTokens(cmds: CommandSpec[]): string[] {
+  return cmds.filter((c) => c.takesWorkspace).flatMap((c) => [c.name, ...c.aliases]);
+}
+
+/** Escape a description for a fish single-quoted string. */
+function fishDesc(s: string): string {
+  return s.replace(/\n/g, ' ').replace(/'/g, "'\\''");
+}
+
+/**
+ * Generate a shell completion script. Pure (no I/O) so it's unit-tested. The
+ * generated script completes subcommands at position 1, and for a subcommand
+ * that takes a workspace it completes workspace names by calling back into the
+ * CLI: `<bin> completion --workspaces`. Dynamic values stay fresh without
+ * regenerating the script.
+ */
+export function generateCompletion(shell: Shell, cmds: CommandSpec[], bins: string[] = COMPLETION_BINS): string {
+  const commands = allTokens(cmds).join(' ');
+  const wsCommands = workspaceTokens(cmds).join(' ');
+
+  if (shell === 'bash') {
+    return `# nemus bash completion. Install: nemus completion bash > /etc/bash_completion.d/nemus
+#   (or: nemus completion bash >> ~/.bashrc)
+_nemus_complete() {
+  local cur bin sub
+  # bash does not clear COMPREPLY between completions; reset so a stale result
+  # from a previous TAB can't leak when we return without setting it.
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  bin="\${COMP_WORDS[0]}"
+  local commands="${commands}"
+  local ws_commands="${wsCommands}"
+  if [ "\$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( \$(compgen -W "\$commands" -- "\$cur") )
+    return 0
+  fi
+  if [ "\$COMP_CWORD" -eq 2 ]; then
+    sub="\${COMP_WORDS[1]}"
+    if [[ " \$ws_commands " == *" \$sub "* ]]; then
+      local names
+      names="\$("\$bin" completion --workspaces 2>/dev/null)"
+      COMPREPLY=( \$(compgen -W "\$names" -- "\$cur") )
+      return 0
+    fi
+  fi
+  return 0
+}
+${bins.map((b) => `complete -F _nemus_complete ${b}`).join('\n')}
+`;
+  }
+
+  if (shell === 'zsh') {
+    // Autoloaded form: save as a file named `_nemus` on your $fpath.
+    return `#compdef ${bins.join(' ')}
+# nemus zsh completion. Install: nemus completion zsh > "\${fpath[1]}/_nemus"
+local -a _nemus_commands
+_nemus_commands=(${allTokens(cmds).map((t) => `'${t}'`).join(' ')})
+local _nemus_ws_commands="${wsCommands}"
+if (( CURRENT == 2 )); then
+  compadd -- $_nemus_commands
+  return
+fi
+if (( CURRENT == 3 )); then
+  local sub=\${words[2]}
+  if [[ " $_nemus_ws_commands " == *" $sub "* ]]; then
+    local -a _nemus_names
+    _nemus_names=(\${(f)"$(\${words[1]} completion --workspaces 2>/dev/null)"})
+    compadd -- $_nemus_names
+  fi
+fi
+`;
+  }
+
+  // fish
+  const lines: string[] = ['# nemus fish completion. Install: nemus completion fish > ~/.config/fish/completions/nemus.fish'];
+  for (const bin of bins) {
+    lines.push(`complete -c ${bin} -f`);
+    for (const c of cmds) {
+      for (const tok of [c.name, ...c.aliases]) {
+        lines.push(`complete -c ${bin} -n __fish_use_subcommand -a '${tok}' -d '${fishDesc(c.description)}'`);
+      }
+    }
+    const wsToks = workspaceTokens(cmds).join(' ');
+    if (wsToks) {
+      lines.push(
+        `complete -c ${bin} -n '__fish_seen_subcommand_from ${wsToks}' -a '(${bin} completion --workspaces)'`,
+      );
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+/** Distill the program's top-level commands into CommandSpecs. */
+export function specsFromProgram(program: Command): CommandSpec[] {
+  return program.commands
+    .map((c) => {
+      const args = (c as any).registeredArguments ?? [];
+      const firstArg: string | undefined = args[0]?.name?.();
+      return {
+        name: c.name(),
+        aliases: c.aliases(),
+        takesWorkspace: typeof firstArg === 'string' && firstArg.toLowerCase().includes('workspace'),
+        description: c.description() ?? '',
+      };
+    })
+    // The completion command itself and any hidden helper needn't clutter, but
+    // keeping them is harmless; only drop entries with no name.
+    .filter((s) => s.name);
+}
+
+export function registerCompletionCommand(program: Command) {
+  program
+    .command('completion [shell]')
+    .description('Output a shell completion script (bash|zsh|fish)')
+    .option('--workspaces', 'Print workspace names (used internally by completion scripts)')
+    .action(async (shell: string | undefined, opts: { workspaces?: boolean }) => {
+      // Data helper the generated scripts call back into.
+      if (opts.workspaces) {
+        try {
+          const workspaces = await listWorkspaces(false);
+          for (const ws of workspaces) process.stdout.write(ws.name + '\n');
+        } catch {
+          // Silent: completion must never error out the user's shell.
+        }
+        return;
+      }
+
+      const shells: Shell[] = ['bash', 'zsh', 'fish'];
+      if (!shell || !shells.includes(shell as Shell)) {
+        logError(`completion: specify a shell — one of ${shells.join(', ')}`);
+        logError('e.g. nemus completion bash');
+        process.exit(1);
+      }
+      process.stdout.write(generateCompletion(shell as Shell, specsFromProgram(program)));
+    });
+}

package/src/program.ts

@@ -58,6 +58,7 @@ import { registerGhqStatusCommand } from './commands/ghq-status';
 import { registerSaveContextCommand } from './commands/save-context';
 import { registerMigrateCommand } from './commands/migrate';
 import { registerReportBugCommand } from './commands/report-bug';
+import { registerCompletionCommand } from './commands/completion';
 
 registerCreateCommand(program);
 registerListCommand(program);
@@ -82,6 +83,7 @@ registerGhqStatusCommand(program);
 registerSaveContextCommand(program);
 registerMigrateCommand(program);
 registerReportBugCommand(program);
+registerCompletionCommand(program);
 
 // Register TUI (delegates to existing Ink/React implementation)
 program