@sap/cds-dk 10.0.7 → 10.1.0

package/bin/completion/index.js

@@ -1,15 +1,31 @@
+const fs = require('node:fs');
 const path = require('node:path');
 
 const cds = require('../../bin/cds');
 const { bold } = require('../../lib/util/term');
+const completionFs = require('./completionFs');
+const completionSetup = require('../../lib/init/template/completion/completionSetup');
 
+// Sentinel factories — returned by staticCompletions() to mark special argument types.
+const FILE  = (exts) => exts ? { type: ':file', ext: exts.split(',').map(e => e.trim()) } : ':file';
+const DIR   = () => ':dir';
+const COMMA = (values) => ({ type: ':comma', values });
 
+// The '_' key in a staticCompletions map marks the default positional argument.
+const POSITIONAL_KEY = '_';
+
+const isFileSentinel = s => s === ':file' || s === ':dir' || (s?.type === ':file' && Array.isArray(s.ext));
+const fileRegex      = s => s.ext ? new RegExp(`\\.(${s.ext.join('|')})$`) : null;
+const filePs1        = s => s.ext ? `':file:${s.ext.join(',')}'` : `'${s}'`;
 
 module.exports = Object.assign(completion, {
-    handleCompletion,
+    staticCompletions: () => ({ '--shell': completionSetup.supportedShells }),
+    FILE,
+    DIR,
+    COMMA,
     options: ['--shell', '--curr', '--line', '--prev'],
     shortcuts: ['-s'],
-    flags: ['--add', '--profile', '--remove'],
+    flags: ['--add', '--profile', '--generate', '--remove'],
     help: `
 # SYNOPSIS
 
@@ -41,6 +57,13 @@ module.exports = Object.assign(completion, {
     *--remove*
         Remove shell completion for cds commands (see examples).
 
+    *--profile* _(deprecated)_
+        Print the path to the completion script for the given shell.
+
+    *--generate*
+        Generate a static completion script for the given shell and print it to stdout.
+        Used by 'npm run build:completion' to pre-build the bundled cache files.
+
     *--shell* <bash | fish | gitbash | ps | zsh>
         Force the shell completion code to be added to the correct shell profile file.
             bash: macOS, Linux, WSL
@@ -65,22 +88,13 @@ module.exports = Object.assign(completion, {
 function getScriptFile(shell) {
     switch (shell) {
         case 'bash':
-        case 'gitbash':
-            return 'cds-bash.sh';
-        case 'fish':
-            return 'cds-fish.fish';
-        case 'ps':
-            return 'cds-ps.ps1';
-        case 'zsh':
-            return 'cds-zsh.sh';
-        case '':
-        case undefined:
-        case null:
-            throw 'Internal error: option --shell is missing';
-        default: {
-            const completionSetup = require('../../lib/init/template/completion/completionSetup');
+        case 'gitbash': return 'cds.sh';
+        case 'fish':    return 'cds.fish';
+        case 'ps':      return 'cds.ps1';
+        case 'zsh':     return 'cds.zsh';
+        default:
+            if (!shell) throw 'Internal error: option --shell is missing';
             throw `Internal error: unsupported shell: ${shell}, supported shells are ${completionSetup.supportedShells.join(', ')}`;
-        }
     }
 }
 
@@ -90,7 +104,24 @@ async function completion(_argv, options) {
         return console.log(path.join(__dirname, 'scripts', scriptFile));
     }
 
-    const completionSetup = require('../../lib/init/template/completion/completionSetup');
+    if (options.generate) {
+        if (options.shell) {
+            const content = await generateStaticScript(options.shell);
+            return content ? process.stdout.write(content) : undefined;
+        }
+        const shells = { sh: 'bash', zsh: 'zsh', fish: 'fish', ps1: 'ps' };
+        const scriptsDir = path.join(__dirname, 'scripts');
+        fs.mkdirSync(scriptsDir, { recursive: true });
+        for (const [ext, shell] of Object.entries(shells)) {
+            const content = await generateStaticScript(shell);
+            if (content) {
+                fs.writeFileSync(path.join(scriptsDir, `cds.${ext}`), content);
+                console.log(`Generated cds.${ext}`);
+            }
+        }
+        return;
+    }
+
     if (options.add || options.remove) {
         await completionSetup.setup(options.add, options);
         return;
@@ -113,124 +144,605 @@ async function completion(_argv, options) {
         throw `internal Error: no completion handler found for shell type: ${shell}, supported shells are ${completionSetup.supportedShells.join(', ')}`;
     }
 
-    const currentWord = localOptions.curr?.trim().replace(/^'|'$/g, '');
+    const currentWord  = localOptions.curr?.trim().replace(/^'|'$/g, '');
     const previousWord = localOptions.prev?.trim().replace(/^'|'$/g, '');
-    const line = localOptions.line?.trim().replace(/^'|'$/g, '');
-    const segments = getSegments(line);
-    const cdsCmd = segments[1] || '';
+    const line         = localOptions.line?.trim().replace(/^'|'$/g, '');
+    const segments     = getSegments(line);
+    const cdsCmd       = segments[1] || '';
 
     const completions = await getCompletions(cdsCmd, previousWord, currentWord, segments);
     reply(completions);
 }
 
-async function handleCompletion(currentWord, previousWord, argv) {
-    const allOptionsFlags = ['--add', '--remove', '--shell']
-        .filter(e => !argv.includes(e));
+async function buildCompletionMap() {
+    const commands = cds.cmds ?? [];
+    const commandMap = {};
+    for (const cmd of commands) {
+        try {
+            const obj = cds.load(cmd);
+            const raw = await obj.staticCompletions?.() ?? [];
+            let positionals = [], optionValues = {}, fileCases = {}, commaCases = {};
+            if (Array.isArray(raw)) {
+                positionals = raw;
+            } else {
+                for (const [key, val] of Object.entries(raw)) {
+                    const resolved = await val;
+                    if (resolved?.type === ':comma') {
+                        commaCases[key] = await resolved.values;
+                    } else if (isFileSentinel(resolved)) {
+                        fileCases[key] = resolved;
+                    } else {
+                        optionValues[key] = resolved;
+                    }
+                }
+            }
+            commandMap[cmd] = {
+                options:     (obj.options  ?? []).filter(Boolean),
+                flags:       (obj.flags    ?? []).filter(Boolean),
+                shortcuts:   (obj.shortcuts ?? []).filter(Boolean),
+                positionals,
+                optionValues,
+                fileCases,
+                commaCases,
+            };
+        } catch (e) { cds.debug?.('completion')?.(`skipping command '${cmd}': ${e?.message ?? e}`); }
+    }
+    return { commands, shortcuts: cds.Shortcuts, commandMap };
+}
 
-    if (currentWord?.startsWith('-')) {
-        return allOptionsFlags;
+async function generateStaticScript(shell) {
+    const map = await buildCompletionMap();
+    switch (shell) {
+        case 'bash':
+        case 'gitbash': return generateBash(map);
+        case 'zsh':     return generateZsh(map);
+        case 'fish':    return generateFish(map);
+        case 'ps':      return generatePs(map);
+        default:
+            throw `Internal error: unsupported shell: ${shell}`;
     }
+}
+
+// --- Code generation helpers ---
+
+// Serialises an array of strings for embedding in a shell word-list (e.g. compgen -W "...").
+function shellQuoteList(arr) {
+    return arr.map(s => JSON.stringify(s)).join(' ');
+}
+
+// Returns the single-char shortcuts from the global shortcuts map.
+function singleCharShortcuts(shortcuts) {
+    return Object.entries(shortcuts).filter(([k]) => /^[a-z]$/.test(k));
+}
+
+// Returns the merged, deduplicated, sorted list of all flags/options for a command.
+function sortedFlags(e) {
+    return [...new Set([...e.options, ...e.flags])].sort();
+}
+
+// Generates the bash/zsh case block that resolves single-char shortcuts to canonical names.
+function shortcutCaseBlock(shortcuts, indent = '    ') {
+    const entries = singleCharShortcuts(shortcuts)
+        .map(([k, v]) => `${indent}    ${k}) cmd=${v} ;;`)
+        .join('\n');
+    if (!entries) return '';
+    return `${indent}case "$cmd" in\n${entries}\n${indent}esac\n`;
+}
+
+// Bash: expression that completes to files matching a sentinel's extensions.
+function bashFileExpr(sentinel) {
+    if (!sentinel.ext) return 'compgen -f -- "$current"';
+    return `compgen -f -- "$current" | grep -E '\\.(${sentinel.ext.join('|')})$'`;
+}
+
+// Zsh: compadd call that completes to files matching a sentinel's extensions.
+function zshFileComp(sentinel) {
+    if (!sentinel.ext) return '_files';
+    return `_files -g '(${sentinel.ext.map(e => `*.${e}`).join('|')})'`;
+}
+
+// Fish: expression that completes to files matching a sentinel's extensions.
+function fishFileComp(sentinel) {
+    if (!sentinel.ext) return '__fish_complete_path';
+    return `string match -r '\\.(${sentinel.ext.join('|')})\\$' -- (__fish_complete_path)`;
+}
+
+// Reads a shell template and substitutes {{PLACEHOLDER}} tokens.
+// Note: replacement strings go through String.replaceAll, so '$' must be doubled
+// ('$$$$' → '$$' → '$') to prevent JS from interpreting '$1' etc. as back-references.
+async function applyTemplate(templateFile, replacements) {
+    const tmpl = await fs.promises.readFile(path.join(__dirname, 'templates', templateFile), 'utf8');
+    return Object.entries(replacements).reduce(
+        (s, [k, v]) => s.replaceAll(`{{${k}}}`, v.replaceAll('$', '$$$$')),
+        tmpl
+    );
+}
+
+// --- Per-shell case-block generators ---
+
+// Bash/zsh: option-value completions (previous word is a known flag → offer its values).
+function optionValueCases(commandMap, emitLine) {
+    return Object.entries(commandMap)
+        .map(([cmd, e]) => {
+            const innerLines = [];
+            for (const [flag, val] of Object.entries(e.optionValues ?? {})) {
+                innerLines.push(emitLine(flag, val, null));
+            }
+            for (const [flag, sentinel] of Object.entries(e.fileCases ?? {})) {
+                if (flag === POSITIONAL_KEY) continue;
+                innerLines.push(emitLine(flag, null, sentinel));
+            }
+            if (!innerLines.length) return '';
+            return `        ${cmd})\n            case "$previous" in\n${innerLines.join('\n')}\n            esac ;;\n`;
+        })
+        .filter(Boolean)
+        .join('');
+}
+
+function bashOptionValueCases(commandMap) {
+    return optionValueCases(commandMap, (flag, val, sentinel) => {
+        const expr = sentinel
+            ? (sentinel === DIR() ? 'compgen -d -- "$current"' : bashFileExpr(sentinel))
+            : `compgen -W "${shellQuoteList(val)}" -- "$current"`;
+        return `            ${flag}) COMPREPLY=( $(${expr}) ) ; return 0 ;;`;
+    });
+}
+
+function zshOptionValueCases(commandMap) {
+    return optionValueCases(commandMap, (flag, val, sentinel) => {
+        const comp = sentinel
+            ? (sentinel === DIR() ? '_files -/' : zshFileComp(sentinel))
+            : `compadd -S '' -- ${shellQuoteList([...val].sort())}`;
+        return `            ${flag}) ${comp} ; return ;;`;
+    });
+}
+
+// Bash/zsh: comma-separated option completions.
+// Entries keyed by POSITIONAL_KEY match any previous word (when user didn't type a flag);
+// a guard skips them if the previous word is itself a flag (consuming an option value).
+function bashCommaCases(commandMap) {
+    const S = '$'; // prevent JS template literal from interpolating shell variables
+    return Object.entries(commandMap)
+        .map(([cmd, e]) => {
+            // Sort so POSITIONAL_KEY ('_') entries come last — they use a catch-all pattern.
+            const entries = Object.entries(e.commaCases ?? {}).sort(([a], [b]) =>
+                a === POSITIONAL_KEY ? 1 : b === POSITIONAL_KEY ? -1 : 0
+            );
+            if (!entries.length) return '';
+            const innerLines = entries.map(([flag, val]) => {
+                const list    = shellQuoteList(val);
+                const pattern = flag === POSITIONAL_KEY ? '*' : flag;
+                // For positional entries: skip if previous word looks like a flag (it's consuming a value).
+                const guard   = flag === POSITIONAL_KEY
+                    ? `                [[ "$previous" == -* ]] && return 0\n`
+                    : '';
+                const body = [
+                    guard + `                local prefix="" partial="" IFS=,`,
+                    `                if [[ "$current" == *,* ]]; then`,
+                    `                    prefix="` + S + `{current%,*},"`,
+                    `                    partial="` + S + `{current##*,}"`,
+                    `                else`,
+                    `                    partial="$current"`,
+                    `                fi`,
+                    `                local -a _used`,
+                    `                read -ra _used <<< "` + S + `{prefix%,}"`,
+                    `                local _all=(${list})`,
+                    `                for v in "` + S + `{_all[@]}"; do`,
+                    `                    [[ " ` + S + `{_used[*]} " == *" $v "* ]] && continue`,
+                    `                    [[ "$v" == "$partial"* ]] && COMPREPLY+=("$prefix$v")`,
+                    `                done`,
+                    `                [[ ` + S + `{#COMPREPLY[@]} -gt 0 ]] && { compopt -o nospace; return 0; } ;;`,
+                ].join('\n');
+                return `            ${pattern})\n${body}`;
+            });
+            return `        ${cmd})\n            case "$previous" in\n${innerLines.join('\n')}\n            esac ;;\n`;
+        })
+        .filter(Boolean)
+        .join('');
+}
+
+function zshCommaCases(commandMap) {
+    const S = '$'; // prevent JS template literal from interpolating shell variables
+    return Object.entries(commandMap)
+        .map(([cmd, e]) => {
+            const entries = Object.entries(e.commaCases ?? {}).sort(([a], [b]) =>
+                a === POSITIONAL_KEY ? 1 : b === POSITIONAL_KEY ? -1 : 0
+            );
+            if (!entries.length) return '';
+            const innerLines = entries.map(([flag, val]) => {
+                const list    = shellQuoteList(val);
+                const pattern = flag === POSITIONAL_KEY ? `*)` : `${flag})`;
+                // For positional entries: skip if previous word looks like a flag (it's consuming a value).
+                const guard   = flag === POSITIONAL_KEY
+                    ? `                [[ "$previous" == -* ]] && return\n`
+                    : '';
+                const body = [
+                    guard + `                local -a _used=("` + S + `{(s:,:)current}")`,
+                    `                local prefix="` + S + `{(j:,:)_used[1,-2]}" partial="` + S + `{_used[-1]}"`,
+                    `                [[ -n "$prefix" ]] && prefix="$prefix,"`,
+                    `                local -a _all=(${list}) _result=()`,
+                    `                for v in "` + S + `{_all[@]}"; do`,
+                    `                    (( ` + S + `{_used[(Ie)$v]} )) && continue`,
+                    `                    [[ "$v" == "$partial"* ]] && _result+=("$v")`,
+                    `                done`,
+                    `                compadd -p "$prefix" -S '' -- "` + S + `{_result[@]}" ; return ;;`,
+                ].join('\n');
+                return `            ${pattern}\n${body}`;
+            });
+            return `        ${cmd})\n            case "$previous" in\n${innerLines.join('\n')}\n            esac ;;\n`;
+        })
+        .filter(Boolean)
+        .join('');
+}
 
-    if (previousWord === '--shell') {
-        const { supportedShells } = require('../../lib/init/template/completion/completionSetup');
-        return supportedShells;
+// --- Static script generators ---
+
+async function generateBash(map) {
+    const { commands, shortcuts, commandMap } = map;
+
+    const flagCases = Object.entries(commandMap)
+        .map(([cmd, e]) => {
+            const flags = sortedFlags(e);
+            if (!flags.length) return '';
+            return `            ${cmd}) COMPREPLY=( $(compgen -W "${shellQuoteList(flags)}" -- "$current") ) ;;`;
+        })
+        .filter(Boolean)
+        .join('\n');
+
+    const fileCases = Object.entries(commandMap)
+        .map(([cmd, e]) => {
+            const sentinel = e.fileCases?.[POSITIONAL_KEY];
+            if (!sentinel) return '';
+            const expr = sentinel === DIR() ? 'compgen -d -- "$current"' : bashFileExpr(sentinel);
+            return `            ${cmd}) COMPREPLY=( $(${expr}) ) ;;`;
+        })
+        .filter(Boolean)
+        .join('\n');
+
+    const stringPositionalCases = Object.entries(commandMap)
+        .map(([cmd, e]) => {
+            if (e.fileCases?.[POSITIONAL_KEY] || !e.positionals?.length) return '';
+            return `            ${cmd}) COMPREPLY=( $(compgen -W "${shellQuoteList([...e.positionals].sort())}" -- "$current") ) ;;`;
+        })
+        .filter(Boolean)
+        .join('\n');
+
+    return applyTemplate('cds-tmpl.sh', {
+        SHORTCUT_CASE:           shortcutCaseBlock(shortcuts),
+        COMMANDS:                shellQuoteList(commands),
+        FLAG_CASES:              flagCases,
+        OPTION_VALUE_CASES:      bashOptionValueCases(commandMap),
+        COMMA_CASES:             bashCommaCases(commandMap),
+        FILE_CASES:              fileCases,
+        STRING_POSITIONAL_CASES: stringPositionalCases,
+    });
+}
+
+async function generateZsh(map) {
+    const { commands, shortcuts, commandMap } = map;
+
+    const flagCases = Object.entries(commandMap)
+        .map(([cmd, e]) => {
+            const flags = sortedFlags(e);
+            if (!flags.length) return '';
+            return `        ${cmd}) compadd -S '' -- ${shellQuoteList(flags)} ;;`;
+        })
+        .filter(Boolean)
+        .join('\n');
+
+    const fileCases = Object.entries(commandMap)
+        .map(([cmd, e]) => {
+            const sentinel = e.fileCases?.[POSITIONAL_KEY];
+            if (!sentinel) return '';
+            const comp = sentinel === DIR() ? '_files -/' : zshFileComp(sentinel);
+            return `        ${cmd}) ${comp} ; return ;;`;
+        })
+        .filter(Boolean)
+        .join('\n');
+
+    const stringPositionalCases = Object.entries(commandMap)
+        .map(([cmd, e]) => {
+            if (e.fileCases?.[POSITIONAL_KEY] || !e.positionals?.length) return '';
+            return `        ${cmd}) compadd -S '' -- ${shellQuoteList([...e.positionals].sort())} ; return ;;`;
+        })
+        .filter(Boolean)
+        .join('\n');
+
+    return applyTemplate('cds-tmpl.zsh', {
+        SHORTCUT_CASE:           shortcutCaseBlock(shortcuts),
+        COMMANDS:                shellQuoteList(commands),
+        FLAG_CASES:              flagCases,
+        OPTION_VALUE_CASES:      zshOptionValueCases(commandMap),
+        COMMA_CASES:             zshCommaCases(commandMap),
+        FILE_CASES:              fileCases,
+        STRING_POSITIONAL_CASES: stringPositionalCases,
+    });
+}
+
+async function generateFish(map) {
+    const { commands, shortcuts, commandMap } = map;
+
+    // Reverse map: canonical command name → its single-char shortcut(s).
+    const cmdShortcuts = {};
+    for (const [shortcut, cmd] of singleCharShortcuts(shortcuts)) {
+        (cmdShortcuts[cmd] ??= []).push(shortcut);
+    }
+
+    // Fish condition: fires when the subcommand (or one of its shortcuts) is already on the line.
+    const seenCmd = (cmd) =>
+        `__fish_seen_subcommand_from ${[cmd, ...(cmdShortcuts[cmd] ?? [])].join(' ')}`;
+
+    const allCmdsAndShortcuts = [
+        ...commands,
+        ...singleCharShortcuts(shortcuts).map(([k]) => k),
+    ].join(' ');
+
+    const lines = [];
+
+    // Top-level commands — only shown before any subcommand is committed.
+    for (const cmd of commands) {
+        lines.push(`complete -c cds -f -n '__fish_use_subcommand' -a '${cmd}'`);
+    }
+
+    for (const [cmd, e] of Object.entries(commandMap)) {
+        const hasFileSentinel = !!e.fileCases?.[POSITIONAL_KEY];
+
+        // File-sentinel positionals (e.g. *.cds, *.json for compile).
+        for (const [flag, sentinel] of Object.entries(e.fileCases ?? {})) {
+            const fishComp = sentinel === DIR() ? '__fish_complete_directories' : fishFileComp(sentinel);
+            const cond = flag === POSITIONAL_KEY
+                ? seenCmd(cmd)
+                : `${seenCmd(cmd)} && __fish_prev_arg_in ${flag}`;
+            lines.push(`complete -c cds -f -n '${cond}' -a "(${fishComp})"`);
+        }
+
+        // String positionals (e.g. command names for `cds help`).
+        for (const pos of [...(e.positionals ?? [])].sort()) {
+            lines.push(`complete -c cds -f -n '${seenCmd(cmd)}' -a '${pos}'`);
+        }
+
+        // Flags — gated on current token starting with '-' when a file sentinel is present,
+        // so that `cds compile <tab>` shows files only and `cds compile --<tab>` shows flags.
+        const flagCond = hasFileSentinel
+            ? `${seenCmd(cmd)} && string match -q -- "-*" (commandline -ct)`
+            : seenCmd(cmd);
+        for (const token of sortedFlags(e)) {
+            lines.push(`complete -c cds -f -n '${flagCond}' -a '${token}'`);
+        }
+
+        // Option values (previous word is a known flag → offer its static values).
+        for (const [flag, val] of Object.entries(e.optionValues ?? {})) {
+            lines.push(`complete -c cds -f -n '${seenCmd(cmd)} && __fish_prev_arg_in ${flag}' -a '${[...val].sort().join(' ')}'`);
+        }
+
+        // Comma-separated values — delegated to the _cdsCommaComplete helper in the template.
+        for (const [flag, val] of Object.entries(e.commaCases ?? {})) {
+            const values = [...val].sort().join(' ');
+            const cond = flag === POSITIONAL_KEY
+                ? seenCmd(cmd)
+                : `${seenCmd(cmd)} && __fish_prev_arg_in ${flag}`;
+            lines.push(`complete -c cds -f -n '${cond}' -a "(_cdsCommaComplete ${values})"`);
+        }
     }
 
-    return allOptionsFlags;
+    return applyTemplate('cds-tmpl.fish', {
+        COMMAND_COMPLETIONS:     lines.join('\n'),
+        CMD_LIST:                commands.join(' '),
+        CMD_LIST_WITH_SHORTCUTS: allCmdsAndShortcuts,
+    });
 }
 
+async function generatePs(map) {
+    const { commands, shortcuts, commandMap } = map;
+
+    const cmdArray = commands.map(c => `'${c}'`).join(', ');
+
+    const shortcutEntries = singleCharShortcuts(shortcuts)
+        .map(([k, v]) => `    '${k}' = '${v}'`)
+        .join(";\n");
+
+    const cmdEntries = Object.entries(commandMap)
+        .map(([cmd, e]) => {
+            const flags = sortedFlags(e).map(t => `'${t}'`).join(', ');
+            return `    '${cmd}' = @(${flags})`;
+        })
+        .join(";\n");
+
+    const positionalEntries = Object.entries(commandMap)
+        .filter(([, e]) => e.positionals?.length)
+        .map(([cmd, e]) => `    '${cmd}' = @(${[...e.positionals].sort().map(p => `'${p}'`).join(', ')})`)
+        .join(";\n");
+
+    const optionValueEntries = Object.entries(commandMap)
+        .filter(([, e]) => Object.keys(e.optionValues ?? {}).length || Object.keys(e.fileCases ?? {}).length)
+        .map(([cmd, e]) => {
+            const inner = [];
+            for (const [flag, val] of Object.entries(e.optionValues ?? {})) {
+                inner.push(`        '${flag}' = @(${[...val].sort().map(v => `'${v}'`).join(', ')})`);
+            }
+            for (const [flag, sentinel] of Object.entries(e.fileCases ?? {})) {
+                inner.push(`        '${flag}' = ${filePs1(sentinel)}`);
+            }
+            return `    '${cmd}' = @{\n${inner.join(";\n")}\n    }`;
+        })
+        .join(";\n");
+
+    const commaEntries = Object.entries(commandMap)
+        .filter(([, e]) => Object.keys(e.commaCases ?? {}).length)
+        .map(([cmd, e]) => {
+            const inner = Object.entries(e.commaCases).map(([flag, val]) =>
+                `        '${flag}' = @(${[...val].sort().map(v => `'${v}'`).join(', ')})`
+            );
+            return `    '${cmd}' = @{\n${inner.join(";\n")}\n    }`;
+        })
+        .join(";\n");
+
+    return applyTemplate('cds-tmpl.ps1', {
+        CMD_ARRAY:            cmdArray,
+        SHORTCUT_ENTRIES:     shortcutEntries,
+        POSITIONAL_ENTRIES:   positionalEntries,
+        OPTION_VALUE_ENTRIES: optionValueEntries,
+        COMMA_ENTRIES:        commaEntries,
+        CMD_ENTRIES:          cmdEntries,
+    });
+}
+
+// --- Completion engine ---
+
 function reply(values) {
-    if (!Array.isArray(values) || values.length === 0) {
-        return;
-    }
+    if (!Array.isArray(values) || values.length === 0) return;
 
-    values = values.filter(e => !!(typeof e === 'string' && e.trim()));
-    values = [...new Set(values)];
+    values = [...new Set(values.filter(e => typeof e === 'string' && e.trim()))];
     values.sort((a, b) => {
-        if (a.startsWith('-') && !b.startsWith('-')) { return 1; }
-        if (!a.startsWith('-') && b.startsWith('-')) { return -1; }
+        // Files / positionals before flags, then alphabetical within each group.
+        const aIsFlag = a.startsWith('-');
+        const bIsFlag = b.startsWith('-');
+        if (aIsFlag !== bIsFlag) return aIsFlag ? 1 : -1;
         return a.localeCompare(b);
     });
 
     console.log(values.join('\n'));
 }
 
+// Splits a shell command line into tokens, respecting quoted strings and escaped spaces.
 function getSegments(line) {
     const cliSplit = /'(.*?)'|"(.*?)"|(\\,|\\ |[^, ])+/gs;
-    const result = line.match(cliSplit);
-    return result.map(s =>
+    return line.match(cliSplit).map(s =>
         s.trim()
             .replace(/(\\ )/g, ' ')
             .replace(/^["']|["']$/g, '')
     );
 }
 
+// Loads the cds command object for the given name, resolving single-char shortcuts first.
 function getCdsCmd(cdsCmd) {
     cdsCmd = cds.Shortcuts?.[cdsCmd] ?? cdsCmd;
     return cds.load(cdsCmd);
 }
 
+// Returns all completable flags/options for a command, excluding flags already used on the line.
 function getAllOptions(cdsCmdObj, segments) {
     return [
         ...cdsCmdObj.options ?? [],
-        ...cdsCmdObj.flags?.filter(o => !segments.includes(o)) ?? []
+        ...cdsCmdObj.flags?.filter(o => !segments.includes(o)) ?? [],
     ];
 }
 
-function getUtil() {
-    const completionFs = require('./completionFs');
-    return {
-        cds,
-        completionFs
-    }
-}
-
 async function getCompletions(cdsCmd, previousWord, currentWord, segments) {
-    const _filter = (completions, currentWord) => {
-        return completions.filter(token => token?.startsWith(currentWord));
-    }
-
-    const _getCompletions = async () => {
+    // Returns completions filtered by currentWord prefix, unless commaFiltered is set
+    // (comma logic pre-filters its own results to avoid double-filtering).
+    let commaFiltered = false;
+
+    const resolveComma = (values, commaStr, partial) => {
+        commaFiltered = true;
+        const parts      = commaStr.split(',');
+        const alreadyUsed = new Set(parts.slice(0, -1).map(s => s.trim()).filter(Boolean));
+        const prefix      = parts.slice(0, -1).join(',') + (parts.length > 1 ? ',' : '');
+        return values.filter(v => !alreadyUsed.has(v) && v.startsWith(partial)).map(v => prefix + v);
+    };
+
+    // Reads the file/dir sentinel for a resolved entry and returns matching paths.
+    const resolveSentinel = (sentinel, word) => {
+        if (sentinel === DIR())      return completionFs.readdir(word, { files: false });
+        if (isFileSentinel(sentinel)) return completionFs.readdir(word, fileRegex(sentinel) ? { fileRegex: fileRegex(sentinel) } : {});
+        return null;
+    };
+
+    const computeCompletions = async () => {
+        // If the cursor is right after 'cds', offer top-level command names.
         if (previousWord === 'cds') {
-            if (!currentWord) {
-                return cds.cmds;
-            } else {
-                const completions = _filter(cds.cmds, currentWord);
-                if (completions.length > 0) {
-                    return completions;
-                }
-                cdsCmd = 'compile';
-                previousWord = 'compile';
-            }
+            if (!currentWord) return cds.cmds;
+            const matching = cds.cmds.filter(c => c.startsWith(currentWord));
+            if (matching.length) return matching;
+            // No command matched the typed prefix — fall through as if typing a compile file arg.
+            cdsCmd = 'compile';
+            previousWord = 'compile';
         }
 
         try {
             const cdsCmdObj = getCdsCmd(cdsCmd);
-            if (typeof cdsCmdObj.handleCompletion === 'function') {
-                return await cdsCmdObj.handleCompletion(currentWord, previousWord, segments, getUtil());
-            }
 
-            if (currentWord?.startsWith('-')) {
-                return getAllOptions(cdsCmdObj, segments);
+            // Current token starts with '-' → offer flags/options.
+            if (currentWord?.startsWith('-')) return getAllOptions(cdsCmdObj, segments);
+
+            const raw = await cdsCmdObj.staticCompletions?.();
+            if (raw && !Array.isArray(raw)) {
+                // Resolve single-char option shortcuts (e.g. -4 → --for) so we can look up
+                // the right key in the staticCompletions map.
+                const cmdOptions   = cdsCmdObj.options   ?? [];
+                const cmdShortcuts = cdsCmdObj.shortcuts ?? [];
+                const shortcutIdx  = cmdShortcuts.indexOf(previousWord);
+                const lookupKey    = shortcutIdx !== -1 ? (cmdOptions[shortcutIdx] ?? previousWord) : previousWord;
+
+                // Comma-separated values come in two forms:
+                //   inline:          "--add approuter,m"     → prev="--add"      curr="approuter,m"
+                //   space-separated: "--add approuter, m"    → prev="approuter," curr="m"
+                const isSpaceSeparated = lookupKey.endsWith(',');
+                const isInlineComma    = !isSpaceSeparated && currentWord?.includes(',');
+                if (isSpaceSeparated || isInlineComma) {
+                    // For space-separated form, find the originating option flag in the segments.
+                    const optKey = isSpaceSeparated
+                        ? cmdOptions.find(o =>
+                            segments.includes(o) ||
+                            cmdShortcuts.some((s, i) => segments.includes(s) && cmdOptions[i] === o)
+                          )
+                        : lookupKey;
+                    const resolved = optKey ? await raw[optKey] : undefined;
+                    if (resolved?.type === ':comma') {
+                        const values   = await resolved.values;
+                        const commaStr = isSpaceSeparated ? previousWord : currentWord;
+                        const partial  = isSpaceSeparated ? (currentWord ?? '') : commaStr.split(',').at(-1);
+                        return resolveComma(values, commaStr, partial);
+                    }
+                }
+
+                // Previous word is a known option → offer its static values or file completions.
+                const entry = raw[lookupKey];
+                if (entry !== undefined) {
+                    const resolved = await entry;
+                    if (resolved?.type === ':comma') {
+                        const values = await resolved.values;
+                        return resolveComma(values, currentWord ?? '', (currentWord ?? '').split(',').at(-1));
+                    }
+                    return resolveSentinel(resolved, currentWord) ?? resolved;
+                }
+
+                // No option matched — check the default positional sentinel.
+                const defaultPositional = raw[POSITIONAL_KEY] !== undefined ? await raw[POSITIONAL_KEY] : undefined;
+                if (defaultPositional !== undefined) {
+                    if (defaultPositional?.type === ':comma') {
+                        const values = await defaultPositional.values;
+                        return resolveComma(values, currentWord ?? '', (currentWord ?? '').split(',').at(-1));
+                    }
+                    return resolveSentinel(defaultPositional, currentWord) ?? [];
+                }
+
+                // Previous word is a consumed option value (e.g. "approuter" after "--add").
+                // Don't offer more positionals — the user has already provided one.
+                const allOpts = [...cmdOptions, ...cmdShortcuts, ...(cdsCmdObj.flags ?? [])];
+                if (previousWord !== cdsCmd && !allOpts.includes(previousWord)) return [];
             }
 
-            const completionFs = require('./completionFs');
-            const all = await completionFs.readdir(currentWord);
-            if (!(cdsCmdObj.options?.includes(previousWord) || cdsCmdObj.shortcuts?.includes(previousWord))) {
-                const allOptions = getAllOptions(cdsCmdObj, segments);
-                all.push(...allOptions);
+            // Array form of staticCompletions → fixed positional list (e.g. cds help <tab>).
+            if (Array.isArray(raw) && raw.length) {
+                const prevIsOption = cdsCmdObj.options?.includes(previousWord) || cdsCmdObj.shortcuts?.includes(previousWord);
+                return prevIsOption ? [] : raw;
             }
 
-            return all;
+            // No staticCompletions — fall back to files + available flags.
+            const files = await completionFs.readdir(currentWord);
+            const prevIsOption = cdsCmdObj.options?.includes(previousWord) || cdsCmdObj.shortcuts?.includes(previousWord);
+            if (!prevIsOption) files.push(...getAllOptions(cdsCmdObj, segments));
+            return files;
+
         } catch {
             return [];
         }
-    }
+    };
 
-    let completions = await _getCompletions();
-    if (currentWord) {
-        completions = _filter(completions, currentWord);
+    let completions = await computeCompletions();
+    if (currentWord && !commaFiltered) {
+        completions = completions.filter(c => c?.startsWith(currentWord));
     }
-
     return completions;
 }