@nemus-cli/nemus 0.2.12 → 0.3.0

package/dist/utils/reflect.js

@@ -0,0 +1,345 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REFLECT_SCHEMA = void 0;
+exports.distillTranscript = distillTranscript;
+exports.findLatestTranscriptFile = findLatestTranscriptFile;
+exports.gatherReflectionCorpus = gatherReflectionCorpus;
+exports.buildJudgePrompt = buildJudgePrompt;
+exports.parseReflectionReport = parseReflectionReport;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const workspace_meta_1 = require("./workspace-meta");
+const agent_config_1 = require("./agent-config");
+const claude_sessions_1 = require("./claude-sessions");
+// --------------------------------------------------------- transcript distill
+const MAX_PROMPTS = 25;
+const MAX_ERRORS = 25;
+const PROMPT_CHARS = 600;
+const ERROR_CHARS = 300;
+/** Flatten a message `content` (string or content-block array) to plain text. */
+function contentToText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((b) => (b && b.type === 'text' && typeof b.text === 'string' ? b.text : ''))
+            .filter(Boolean)
+            .join('\n');
+    }
+    return '';
+}
+// Only used as a FALLBACK when a tool result carries no explicit error flag.
+// Kept to strong failure signals so a successful grep/log line for the word
+// "error", or a passing test named “…error…”, isn't mistaken for a failure.
+const ERROR_RE = /\b(fatal|failed|failure|exception|traceback|denied|not a git repository|timed out|exit code\s+[1-9])\b/i;
+/**
+ * Decide whether a tool result is a failure: trust the explicit `isError` flag
+ * when present (true => failure, false => success), and only guess from the
+ * text when there's no flag at all. This keeps the judge's “evidence” to real
+ * failures instead of any output that happens to contain the word “error”.
+ */
+function isToolFailure(flag, text) {
+    if (flag === true)
+        return true;
+    if (flag === false)
+        return false;
+    return ERROR_RE.test(text);
+}
+/**
+ * Distill a raw `.jsonl` transcript into the signals a judge needs: the human
+ * prompts, tool failures, and which tools ran. Pure (operates on file content),
+ * defensive about the several line shapes Claude/pi emit, and bounded so a huge
+ * transcript can't blow the prompt budget.
+ */
+function distillTranscript(raw, meta) {
+    const userPrompts = [];
+    const errors = [];
+    const tools = new Set();
+    let turns = 0;
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const msg = obj.message ?? obj;
+        const role = msg?.role ?? obj?.type;
+        const content = msg?.content;
+        // Assistant turn + tool uses. Claude uses `tool_use` blocks; pi uses `toolCall`.
+        if (role === 'assistant') {
+            turns++;
+            if (Array.isArray(content)) {
+                for (const b of content) {
+                    if (b && (b.type === 'tool_use' || b.type === 'toolCall') && typeof b.name === 'string')
+                        tools.add(b.name);
+                }
+            }
+        }
+        // Tool results, two shapes:
+        //  - pi: a top-level message with role 'toolResult' (+ toolName, content).
+        //  - Claude: a `tool_result` block inside a user message's content array.
+        if (role === 'toolResult') {
+            if (typeof msg.toolName === 'string')
+                tools.add(msg.toolName);
+            const text = contentToText(content);
+            if (isToolFailure(msg.isError ?? msg.is_error, text) && text.trim() && errors.length < MAX_ERRORS) {
+                errors.push(text.trim().slice(0, ERROR_CHARS));
+            }
+        }
+        if (Array.isArray(content)) {
+            for (const b of content) {
+                if (b && b.type === 'tool_result') {
+                    const text = contentToText(b.content);
+                    if (isToolFailure(b.is_error, text) && text.trim() && errors.length < MAX_ERRORS) {
+                        errors.push(text.trim().slice(0, ERROR_CHARS));
+                    }
+                }
+            }
+        }
+        // Human prompts: a user message that carries actual text (not a tool_result echo).
+        if (role === 'user') {
+            const isToolResultOnly = Array.isArray(content) && content.length > 0 && content.every((b) => b?.type === 'tool_result');
+            if (!isToolResultOnly) {
+                const text = contentToText(content).trim();
+                if (text && !text.startsWith('<') && userPrompts.length < MAX_PROMPTS) {
+                    userPrompts.push(text.slice(0, PROMPT_CHARS));
+                }
+            }
+        }
+    }
+    return { sessionId: meta.sessionId, agentType: meta.agentType, turns, userPrompts, errors, tools: [...tools] };
+}
+// --------------------------------------------------------- corpus gathering
+/** Locate the most recent `.jsonl` transcript for a workspace under an agent. */
+async function findLatestTranscriptFile(sessionProjectsDir, workspacePath, agentType) {
+    if (agentType !== 'claude' && agentType !== 'pi')
+        return null;
+    const projDir = path.join(sessionProjectsDir, (0, claude_sessions_1.pathToProjectDirName)(workspacePath, agentType));
+    let entries;
+    try {
+        entries = await fs.readdir(projDir);
+    }
+    catch {
+        return null;
+    }
+    const jsonl = entries.filter((f) => f.endsWith('.jsonl'));
+    if (jsonl.length === 0)
+        return null;
+    const stats = await Promise.all(jsonl.map(async (f) => {
+        try {
+            return { f, mtime: (await fs.stat(path.join(projDir, f))).mtime.getTime() };
+        }
+        catch {
+            return null;
+        }
+    }));
+    const best = stats.filter((s) => !!s).sort((a, b) => b.mtime - a.mtime)[0];
+    return best ? path.join(projDir, best.f) : null;
+}
+const MAX_TRANSCRIPT_BYTES = 4 * 1024 * 1024;
+/** Read + distill the transcript for a specific discovered session. Prefers the
+ *  exact `<sessionId>.jsonl`; falls back to the latest transcript in that
+ *  project dir if the exact file has been rotated away. */
+async function readDigestForSession(s) {
+    if (s.agentType !== 'claude' && s.agentType !== 'pi')
+        return null;
+    const projectsDir = (0, agent_config_1.getAgentPaths)(s.agentType).sessionProjectsDir;
+    const exact = path.join(projectsDir, (0, claude_sessions_1.pathToProjectDirName)(s.workspacePath, s.agentType), `${s.sessionId}.jsonl`);
+    let file = exact;
+    try {
+        await fs.access(exact);
+    }
+    catch {
+        file = await findLatestTranscriptFile(projectsDir, s.workspacePath, s.agentType);
+    }
+    if (!file)
+        return null;
+    let raw;
+    try {
+        raw = await fs.readFile(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    if (raw.length > MAX_TRANSCRIPT_BYTES)
+        raw = raw.slice(raw.length - MAX_TRANSCRIPT_BYTES); // keep the tail (most recent)
+    return distillTranscript(raw, { sessionId: s.sessionId, agentType: s.agentType });
+}
+async function listAvailableSkills() {
+    const names = new Set();
+    for (const dir of (0, agent_config_1.getSkillsTargetDirs)()) {
+        try {
+            for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+                if (entry.isDirectory())
+                    names.add(entry.name);
+                else if (entry.name.endsWith('.md'))
+                    names.add(entry.name.replace(/\.md$/, ''));
+            }
+        }
+        catch {
+            /* dir may not exist */
+        }
+    }
+    return [...names].sort();
+}
+async function contextFilesFor(workspacePath) {
+    const present = [];
+    for (const name of (0, agent_config_1.getAllKnownContextFileNames)()) {
+        try {
+            await fs.access(path.join(workspacePath, name));
+            present.push(name);
+        }
+        catch {
+            /* not present */
+        }
+    }
+    return present;
+}
+/**
+ * Build the corpus the judge reasons over: the `limit` most **recently active**
+ * workspaces (by their latest agent session, not creation date — a retrospective
+ * is about recent *work*), each with its repos, context files, and distilled
+ * session, plus the globally-available skills.
+ */
+async function gatherReflectionCorpus(limit) {
+    const [sessions, workspaces, availableSkills] = await Promise.all([
+        (0, claude_sessions_1.getWorkspaceSessions)(), // already sorted by last-active, one per workspace
+        (0, workspace_meta_1.listWorkspaces)(false),
+        listAvailableSkills(),
+    ]);
+    const metaByName = new Map(workspaces.map((w) => [w.name, w]));
+    const recent = sessions.slice(0, limit);
+    const digests = [];
+    for (const s of recent) {
+        const meta = metaByName.get(s.workspaceName);
+        digests.push({
+            name: s.workspaceName,
+            repoCount: meta?.metadata?.repositories?.length ?? 0,
+            repos: (meta?.metadata?.repositories ?? []).map((r) => r.name),
+            contextFiles: await contextFilesFor(s.workspacePath),
+            session: await readDigestForSession(s),
+        });
+    }
+    return { generatedAt: new Date().toISOString(), availableSkills, workspaces: digests };
+}
+// ------------------------------------------------------------- judge prompt
+/** JSON schema for `claude --json-schema` (best-effort; other agents ignore it). */
+exports.REFLECT_SCHEMA = JSON.stringify({
+    type: 'object',
+    properties: {
+        summary: { type: 'string' },
+        recommendations: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    kind: { type: 'string', enum: ['skill', 'context', 'test', 'prompt', 'connectivity', 'workflow', 'other'] },
+                    title: { type: 'string' },
+                    detail: { type: 'string' },
+                    target: { type: 'string' },
+                    priority: { type: 'string', enum: ['high', 'medium', 'low'] },
+                    example: { type: 'string' },
+                },
+                required: ['kind', 'title', 'detail', 'priority'],
+            },
+        },
+    },
+    required: ['summary', 'recommendations'],
+});
+/**
+ * Build the LLM-as-a-judge prompt. The judge sees distilled recent sessions and
+ * is asked to recommend concrete improvements to the user's SETUP (skills,
+ * AGENTS.md/context rules, connectivity/tests, prompt habits, workflow) — not to
+ * redo the tasks. Output is strict JSON matching REFLECT_SCHEMA.
+ */
+function buildJudgePrompt(corpus) {
+    const lines = [];
+    lines.push('You are an expert reviewer ("LLM as a judge") analyzing an engineer\'s recent AI coding-agent sessions.', 'Goal: recommend concrete improvements to their SETUP so the agent works better next time —', 'which skills to add and WHERE, which AGENTS.md/context rules are missing, missing connectivity/', 'smoke tests, and prompt habits to change. Judge the setup, do NOT redo the tasks.', '', 'Base every recommendation on evidence in the sessions below (repeated failures, retries, vague', 'prompts, missing context). Prefer a few high-signal, actionable items over many generic ones.', 'When you suggest a skill or an AGENTS.md rule, include a short concrete `example` snippet.', '', `Globally installed skills (don't re-suggest these; suggest genuinely missing ones): ${corpus.availableSkills.join(', ') || '(none)'}`, '', `Recent workspaces (${corpus.workspaces.length}):`);
+    for (const ws of corpus.workspaces) {
+        lines.push(`\n## ${ws.name}`);
+        lines.push(`repos: ${ws.repos.join(', ') || '(none)'} | context files: ${ws.contextFiles.join(', ') || 'NONE'}`);
+        if (!ws.session) {
+            lines.push('session: (no recent agent session found)');
+            continue;
+        }
+        lines.push(`session: ${ws.session.turns} turns, tools used: ${ws.session.tools.join(', ') || '(none)'}`);
+        if (ws.session.userPrompts.length) {
+            lines.push('user prompts:');
+            for (const p of ws.session.userPrompts)
+                lines.push(`  - ${p.replace(/\n/g, ' ')}`);
+        }
+        if (ws.session.errors.length) {
+            lines.push('errors/failures observed:');
+            for (const e of ws.session.errors)
+                lines.push(`  - ${e.replace(/\n/g, ' ')}`);
+        }
+    }
+    lines.push('', 'Respond with ONLY a JSON object of this shape (no prose, no markdown fence):', '{"summary": string, "recommendations": [{"kind":"skill|context|test|prompt|connectivity|workflow|other",', '"title": string, "detail": string, "target": string(optional workspace/repo/path),', '"priority":"high|medium|low", "example": string(optional snippet)}]}');
+    return lines.join('\n');
+}
+// ----------------------------------------------------------- response parse
+const KINDS = ['skill', 'context', 'test', 'prompt', 'connectivity', 'workflow', 'other'];
+const PRIORITIES = ['high', 'medium', 'low'];
+/** Validate + normalize the judge's parsed JSON into a ReflectionReport. */
+function parseReflectionReport(parsed) {
+    const obj = (parsed ?? {});
+    const summary = typeof obj.summary === 'string' ? obj.summary : '';
+    const rawRecs = Array.isArray(obj.recommendations) ? obj.recommendations : [];
+    const recommendations = rawRecs
+        .map((r) => {
+        if (!r || typeof r !== 'object')
+            return null;
+        const title = typeof r.title === 'string' ? r.title : '';
+        const detail = typeof r.detail === 'string' ? r.detail : '';
+        if (!title && !detail)
+            return null;
+        const kind = KINDS.includes(r.kind) ? r.kind : 'other';
+        const priority = PRIORITIES.includes(r.priority) ? r.priority : 'medium';
+        const rec = { kind, title, detail, priority };
+        if (typeof r.target === 'string' && r.target.trim())
+            rec.target = r.target.trim();
+        if (typeof r.example === 'string' && r.example.trim())
+            rec.example = r.example.trim();
+        return rec;
+    })
+        .filter((r) => r !== null);
+    return { summary, recommendations };
+}

package/package.json

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

package/src/cli/ai-prompt.ts

@@ -1,4 +1,5 @@
 import { spawn, execFile, execFileSync } from 'child_process';
+import { parseAgentJson } from '../utils/agent-judge';
 import { promisify } from 'util';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -259,32 +260,21 @@ export async function extractIntent(prompt: string): Promise<ExtractedIntent> {
     result = runExtraction('pi', [...piLean, ...piCore], piCore);
   }
 
-  // Strip markdown code fences if present (Pi may wrap JSON in ```json...```)
-  let jsonStr = result.trim();
-  const fenceMatch = jsonStr.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
-  if (fenceMatch) {
-    jsonStr = fenceMatch[1].trim();
-  }
-
-  const parsed = JSON.parse(jsonStr);
-
-  // Handle different output formats:
-  // - Claude: { structured_output: {...} } or { result: "..." }
-  // - Pi: may return the object directly or wrap it
+  // Unwrap the agent's reply (code fences + the structured_output / result-string
+  // / result-object / bare-object envelopes) with the shared parser, so this and
+  // the reflect judge can't drift when a new agent shape is learned. The
+  // extraction-specific INVOCATION (lean flags + tailored timeout/auth errors)
+  // deliberately stays here — those messages are part of the `nemus --` UX.
   let intent: ExtractedIntent | undefined;
-  if (parsed.structured_output) {
-    intent = parsed.structured_output;
-  } else if (typeof parsed.result === 'string' && parsed.result) {
-    try { intent = JSON.parse(parsed.result); } catch { /* ignore */ }
-  } else if (typeof parsed.result === 'object' && parsed.result !== null) {
-    intent = parsed.result;
-  } else if (parsed.workspaceName || parsed.repos || parsed.remainingIntent !== undefined) {
-    // Pi may return the extracted object directly
-    intent = parsed;
+  try {
+    const parsed = parseAgentJson(result) as any;
+    if (parsed && typeof parsed === 'object') intent = parsed;
+  } catch {
+    throw new Error(`Could not extract intent from agent response: ${result.slice(0, 200)}`);
   }
 
   if (!intent) {
-    throw new Error(`Could not extract intent from agent response. Parsed: ${JSON.stringify(parsed).slice(0, 200)}`);
+    throw new Error(`Could not extract intent from agent response: ${result.slice(0, 200)}`);
   }
 
   // Coerce/validate field types so malformed model output can't crash the

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)));
+    });
+}