@xfe-repo/cli 2.0.7 → 2.0.9

package/dist/completion/core.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @xfe-repo/cli - 补全核心（与 UI / shell 协议解耦）
+ *
+ * 集中维护：命令目录条目类型、查询/输入解析、option/value 建议计算、
+ * 已用 flag 过滤、命令寻址、prefilled 提取、模糊匹配。
+ */
+import type { CommandOptionMeta } from './command.js';
+export type CommandCatalogItemType = 'command' | 'group' | 'back' | 'option' | 'value';
+export interface CommandCatalogItem {
+    readonly name: string;
+    readonly description: string;
+    readonly disabled?: boolean;
+    readonly type?: CommandCatalogItemType;
+    readonly children?: CommandCatalogItem[];
+    readonly options?: readonly CommandOptionMeta[];
+}
+export interface ParsedQuery {
+    readonly activeGroup: CommandCatalogItem | null;
+    readonly subQuery: string;
+    readonly topQuery: string;
+}
+export type ExtrasMode = {
+    readonly kind: 'value';
+    readonly command: CommandCatalogItem;
+    readonly key: string;
+    readonly partial: string;
+    readonly values: readonly string[];
+} | {
+    readonly kind: 'name';
+    readonly command: CommandCatalogItem;
+    readonly partial: string;
+    readonly usedNames: ReadonlySet<string>;
+};
+export declare function parseQuery(query: string, options: readonly CommandCatalogItem[]): ParsedQuery;
+export declare function filterTopLevel(options: readonly CommandCatalogItem[], query: string): CommandCatalogItem[];
+export declare function filterSubCommands(options: readonly CommandCatalogItem[], query: string): CommandCatalogItem[];
+export declare function parseExtrasMode(rawQuery: string, options: readonly CommandCatalogItem[]): ExtrasMode | null;
+export declare function buildExtrasSuggestions(mode: ExtrasMode): CommandCatalogItem[];
+export declare function applyExtrasCompletion(input: string, mode: ExtrasMode, selected: string): string;
+export declare function resolveMatchedCommandWithFlags(rawQuery: string, options: readonly CommandCatalogItem[]): CommandCatalogItem | null;
+export declare function extractCommandAndPrefilled(input: string, options: readonly CommandCatalogItem[]): {
+    command: CommandCatalogItem | null;
+    prefilled: Record<string, string>;
+};
+export declare function hasFlagToken(input: string): boolean;
+export type CompletionMode = 'extras' | 'matched' | 'group' | 'search';
+export interface CompletionState {
+    readonly mode: CompletionMode;
+    readonly extrasMode: ExtrasMode | null;
+    readonly activeGroup: CommandCatalogItem | null;
+    readonly subQuery: string;
+    readonly topQuery: string;
+    readonly matchedCommand: CommandCatalogItem | null;
+}
+/**
+ * 从原始查询字符串派生完整补全状态
+ *
+ * 优先级：extras flag 补全 → 命令+flag 已匹配 → 分组导航 → 顶层搜索
+ */
+export declare function buildCompletionState(rawQuery: string, options: readonly CommandCatalogItem[]): CompletionState;
+/** 根据 CompletionState 计算建议列表；group 模式下自动在首项插入「返回上级」条目 */
+export declare function buildSuggestions(state: CompletionState, options: readonly CommandCatalogItem[]): CommandCatalogItem[];
+//# sourceMappingURL=core.d.ts.map

package/dist/completion/core.js

@@ -0,0 +1,237 @@
+/**
+ * @xfe-repo/cli - 补全核心（与 UI / shell 协议解耦）
+ *
+ * 集中维护：命令目录条目类型、查询/输入解析、option/value 建议计算、
+ * 已用 flag 过滤、命令寻址、prefilled 提取、模糊匹配。
+ */
+import { parseCommandFlagTokens, splitCommandName, splitFlagTokens } from './command.js';
+// ─── Public API ─────────────────────────────────────────────
+export function parseQuery(query, options) {
+    if (!query)
+        return { activeGroup: null, subQuery: '', topQuery: '' };
+    const spaceIndex = query.indexOf(' ');
+    if (spaceIndex > 0) {
+        const groupPart = query.slice(0, spaceIndex);
+        const subQuery = query.slice(spaceIndex + 1).trim();
+        const group = options.find((item) => item.type === 'group' && item.name.toLowerCase() === groupPart);
+        if (group)
+            return { activeGroup: group, subQuery, topQuery: '' };
+    }
+    const exactGroup = options.find((item) => item.type === 'group' && item.name.toLowerCase() === query);
+    if (exactGroup)
+        return { activeGroup: exactGroup, subQuery: '', topQuery: '' };
+    return { activeGroup: null, subQuery: '', topQuery: query };
+}
+export function filterTopLevel(options, query) {
+    return options.filter((item) => fuzzyMatch(item.name, query)).sort((a, b) => matchScore(a.name, query) - matchScore(b.name, query));
+}
+export function filterSubCommands(options, query) {
+    return options
+        .filter((item) => {
+        const action = splitCommandName(item.name).action;
+        return fuzzyMatch(action, query) || fuzzyMatch(item.name, query);
+    })
+        .sort((a, b) => {
+        const aAction = splitCommandName(a.name).action;
+        const bAction = splitCommandName(b.name).action;
+        return matchScore(aAction, query) - matchScore(bAction, query);
+    });
+}
+export function parseExtrasMode(rawQuery, options) {
+    const split = splitCommandAndFlags(rawQuery, options);
+    if (!split || !split.command.options?.length)
+        return null;
+    const { command, flagTokens, endsWithSpace } = split;
+    if (flagTokens.length === 0 && !endsWithSpace)
+        return null;
+    const newFlag = endsWithSpace || flagTokens.length === 0;
+    const usedNames = collectUsedNames(newFlag ? flagTokens : flagTokens.slice(0, -1));
+    if (newFlag)
+        return { kind: 'name', command, partial: '', usedNames };
+    const last = flagTokens[flagTokens.length - 1];
+    if (!last.startsWith('--'))
+        return null;
+    const eqIdx = last.indexOf('=');
+    if (eqIdx >= 0) {
+        const rawKey = last.slice(2, eqIdx);
+        const partial = last.slice(eqIdx + 1);
+        const option = command.options?.find((item) => item.name.toLowerCase() === rawKey.toLowerCase());
+        if (!option?.enumValues?.length)
+            return null;
+        return { kind: 'value', command, key: option.name, partial, values: option.enumValues };
+    }
+    return { kind: 'name', command, partial: last.slice(2), usedNames };
+}
+export function buildExtrasSuggestions(mode) {
+    if (mode.kind === 'value') {
+        const partial = mode.partial.toLowerCase();
+        return mode.values
+            .filter((value) => !partial || value.toLowerCase().startsWith(partial))
+            .map((value) => ({ name: value, description: '', type: 'value' }));
+    }
+    const partial = mode.partial.toLowerCase();
+    return (mode.command.options ?? [])
+        .filter((option) => !mode.usedNames.has(option.name.toLowerCase()))
+        .filter((option) => !partial || option.name.toLowerCase().startsWith(partial))
+        .map((option) => ({ name: option.name, description: option.description, type: 'option' }));
+}
+export function applyExtrasCompletion(input, mode, selected) {
+    const lastSpace = input.lastIndexOf(' ');
+    const prefix = input.slice(0, lastSpace + 1);
+    if (mode.kind === 'value')
+        return `${prefix}--${mode.key}=${selected} `;
+    const isBoolean = mode.command.options?.find((option) => option.name === selected)?.isBoolean === true;
+    return `${prefix}${isBoolean ? `--${selected} ` : `--${selected}=`}`;
+}
+export function resolveMatchedCommandWithFlags(rawQuery, options) {
+    const split = splitFlagTokens(rawQuery);
+    if (!split || split.flagTokens.length === 0)
+        return null;
+    if (split.cmdTokens.length === 0 || split.cmdTokens.length > 2)
+        return null;
+    return resolveCommand(split.cmdTokens.join(' '), options);
+}
+export function extractCommandAndPrefilled(input, options) {
+    const raw = input.startsWith('/') ? input.slice(1) : '';
+    const split = splitCommandAndFlags(raw, options);
+    if (!split || split.flagTokens.length === 0)
+        return { command: null, prefilled: {} };
+    return {
+        command: split.command,
+        prefilled: parseCommandFlagTokens(split.flagTokens, split.command.options),
+    };
+}
+export function hasFlagToken(input) {
+    const raw = input.startsWith('/') ? input.slice(1) : input;
+    const split = splitFlagTokens(raw);
+    return !!split && split.flagTokens.length > 0;
+}
+/**
+ * 从原始查询字符串派生完整补全状态
+ *
+ * 优先级：extras flag 补全 → 命令+flag 已匹配 → 分组导航 → 顶层搜索
+ */
+export function buildCompletionState(rawQuery, options) {
+    const extrasMode = parseExtrasMode(rawQuery, options);
+    if (extrasMode) {
+        return { mode: 'extras', extrasMode, activeGroup: null, subQuery: '', topQuery: '', matchedCommand: null };
+    }
+    const matchedCommand = resolveMatchedCommandWithFlags(rawQuery, options);
+    if (matchedCommand) {
+        return { mode: 'matched', extrasMode: null, activeGroup: null, subQuery: '', topQuery: '', matchedCommand };
+    }
+    const { activeGroup, subQuery, topQuery } = parseQuery(rawQuery.toLowerCase(), options);
+    if (activeGroup) {
+        return { mode: 'group', extrasMode: null, activeGroup, subQuery, topQuery: '', matchedCommand: null };
+    }
+    return { mode: 'search', extrasMode: null, activeGroup: null, subQuery: '', topQuery, matchedCommand: null };
+}
+/** 根据 CompletionState 计算建议列表；group 模式下自动在首项插入「返回上级」条目 */
+export function buildSuggestions(state, options) {
+    switch (state.mode) {
+        case 'extras':
+            return buildExtrasSuggestions(state.extrasMode);
+        case 'matched':
+            return [state.matchedCommand];
+        case 'group': {
+            const children = state.activeGroup.children ?? [];
+            const backItem = { name: '__back__', description: '返回上级', type: 'back' };
+            if (!state.subQuery)
+                return [backItem, ...children];
+            return [backItem, ...filterSubCommands(children, state.subQuery)];
+        }
+        case 'search':
+            if (!state.topQuery)
+                return options;
+            return filterTopLevel(options, state.topQuery);
+    }
+}
+// ─── Helpers ────────────────────────────────────────────────
+function splitCommandAndFlags(rawQuery, options) {
+    const split = splitFlagTokens(rawQuery);
+    if (!split || split.cmdTokens.length === 0 || split.cmdTokens.length > 2)
+        return null;
+    const command = resolveCommand(split.cmdTokens.join(' '), options);
+    if (!command)
+        return null;
+    return { command, flagTokens: split.flagTokens, endsWithSpace: split.endsWithSpace };
+}
+function resolveCommand(cmdPart, options) {
+    const parts = cmdPart.trim().split(/\s+/);
+    if (parts.length === 1)
+        return findCommandByName(options, parts[0]);
+    if (parts.length !== 2)
+        return null;
+    const [groupName, action] = parts;
+    const group = options.find((item) => item.type === 'group' && item.name.toLowerCase() === groupName.toLowerCase());
+    if (!group?.children)
+        return null;
+    return group.children.find((child) => splitCommandName(child.name).action.toLowerCase() === action.toLowerCase()) ?? null;
+}
+function findCommandByName(options, name) {
+    const target = name.toLowerCase();
+    const directMatch = findDirectCommand(options, target);
+    if (directMatch)
+        return directMatch;
+    return findUniqueActionMatch(options, target);
+}
+function findDirectCommand(options, target) {
+    for (const item of options) {
+        if (item.type === 'group') {
+            const fullNameMatch = item.children?.find((child) => child.name.toLowerCase() === target);
+            if (fullNameMatch)
+                return fullNameMatch;
+            continue;
+        }
+        if (item.name.toLowerCase() === target)
+            return item;
+    }
+    return null;
+}
+function findUniqueActionMatch(options, target) {
+    let matched = null;
+    for (const item of options) {
+        if (item.type !== 'group' || !item.children)
+            continue;
+        for (const child of item.children) {
+            if (splitCommandName(child.name).action.toLowerCase() !== target)
+                continue;
+            if (matched)
+                return null;
+            matched = child;
+        }
+    }
+    return matched;
+}
+function collectUsedNames(flagTokens) {
+    const used = new Set();
+    for (const token of flagTokens) {
+        if (!token.startsWith('--'))
+            continue;
+        const eq = token.indexOf('=');
+        const name = (eq >= 0 ? token.slice(2, eq) : token.slice(2)).toLowerCase();
+        if (name)
+            used.add(name);
+    }
+    return used;
+}
+function matchScore(text, query) {
+    const lower = text.toLowerCase();
+    if (lower.startsWith(query))
+        return 0;
+    if (lower.includes(query))
+        return 1;
+    return 2;
+}
+function fuzzyMatch(text, query) {
+    const lower = text.toLowerCase();
+    if (lower.includes(query))
+        return true;
+    let queryIndex = 0;
+    for (let i = 0; i < lower.length && queryIndex < query.length; i++) {
+        if (lower[i] === query[queryIndex])
+            queryIndex++;
+    }
+    return queryIndex === query.length;
+}
+//# sourceMappingURL=core.js.map

package/dist/completion/index.d.ts

@@ -0,0 +1,9 @@
+export { getCommandOptionsMeta, parseCommandFlagTokens, splitCommandName, splitFlagTokens } from './command';
+export type { CommandOptionMeta, SplitCommandName } from './command';
+export { buildCommandCatalog } from './catalog';
+export type { BuildCatalogOptions } from './catalog';
+export { applyExtrasCompletion, buildCompletionState, buildExtrasSuggestions, buildSuggestions, extractCommandAndPrefilled, filterSubCommands, filterTopLevel, hasFlagToken, parseExtrasMode, parseQuery, resolveMatchedCommandWithFlags, } from './core';
+export type { CommandCatalogItem, CommandCatalogItemType, CompletionMode, CompletionState, ExtrasMode, ParsedQuery } from './core';
+export { applyCommandOptionMetas, attachEnumOptionValueCompletions, createDynamicCommandBinding, initTabCompletion, installShellCompletion, parsePrefilledFromArgv, uninstallShellCompletion, } from './shell';
+export type { DynamicCommandBinding, TabRoot } from './shell';
+//# sourceMappingURL=index.d.ts.map

package/dist/completion/index.js

@@ -0,0 +1,5 @@
+export { getCommandOptionsMeta, parseCommandFlagTokens, splitCommandName, splitFlagTokens } from './command';
+export { buildCommandCatalog } from './catalog';
+export { applyExtrasCompletion, buildCompletionState, buildExtrasSuggestions, buildSuggestions, extractCommandAndPrefilled, filterSubCommands, filterTopLevel, hasFlagToken, parseExtrasMode, parseQuery, resolveMatchedCommandWithFlags, } from './core';
+export { applyCommandOptionMetas, attachEnumOptionValueCompletions, createDynamicCommandBinding, initTabCompletion, installShellCompletion, parsePrefilledFromArgv, uninstallShellCompletion, } from './shell';
+//# sourceMappingURL=index.js.map

package/dist/completion/shell.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @xfe-repo/cli - Shell 补全 / Commander 适配
+ */
+import type { RootCommand } from '@bomb.sh/tab';
+import tab from '@bomb.sh/tab/commander';
+import type { CommandDefinition } from '@xfe-repo/cli-core';
+import type { Command } from 'commander';
+import type { CommandOptionMeta } from './command.js';
+export type TabRoot = RootCommand;
+export interface DynamicCommandBinding {
+    readonly scriptName: string;
+    readonly namespace: string | null;
+    readonly action: string;
+    readonly tabName: string;
+    readonly optionMetas?: readonly CommandOptionMeta[];
+}
+export declare function initTabCompletion(program: Command): ReturnType<typeof tab>;
+export declare function createDynamicCommandBinding(definition: Pick<CommandDefinition, 'name' | 'parameters'>): DynamicCommandBinding;
+export declare function applyCommandOptionMetas(cmd: Command, optionMetas?: readonly CommandOptionMeta[]): void;
+export declare function attachEnumOptionValueCompletions(root: TabRoot, bindings: readonly DynamicCommandBinding[]): void;
+export declare function parsePrefilledFromArgv(argv: readonly string[], commandSegments: readonly string[], optionMetas?: readonly CommandOptionMeta[]): Record<string, string>;
+export declare function installShellCompletion(): void;
+export declare function uninstallShellCompletion(): void;
+//# sourceMappingURL=shell.d.ts.map

package/dist/completion/shell.js

@@ -0,0 +1,160 @@
+/**
+ * @xfe-repo/cli - Shell 补全 / Commander 适配
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import tab from '@bomb.sh/tab/commander';
+import { getCommandOptionsMeta, parseCommandFlagTokens, splitCommandName } from './command.js';
+// ─── Public API ─────────────────────────────────────────────
+export function initTabCompletion(program) {
+    return tab(program);
+}
+export function createDynamicCommandBinding(definition) {
+    const { namespace, action } = splitCommandName(definition.name);
+    return {
+        scriptName: definition.name,
+        namespace,
+        action,
+        tabName: namespace ? `${namespace} ${action}` : action,
+        optionMetas: getCommandOptionsMeta(definition.parameters),
+    };
+}
+export function applyCommandOptionMetas(cmd, optionMetas) {
+    if (!optionMetas)
+        return;
+    for (const meta of optionMetas) {
+        cmd.option(buildOptionFlags(meta), meta.description || meta.name);
+    }
+}
+export function attachEnumOptionValueCompletions(root, bindings) {
+    for (const binding of bindings) {
+        const tabCommand = root.commands.get(binding.tabName);
+        if (!tabCommand || !binding.optionMetas)
+            continue;
+        for (const meta of binding.optionMetas) {
+            if (!meta.enumValues)
+                continue;
+            const option = tabCommand.options.get(meta.name);
+            if (!option)
+                continue;
+            option.handler = (complete) => {
+                for (const value of meta.enumValues)
+                    complete(value, meta.description);
+            };
+        }
+    }
+}
+export function parsePrefilledFromArgv(argv, commandSegments, optionMetas) {
+    const startIndex = locateSegmentsTail(argv, commandSegments);
+    return parseCommandFlagTokens(argv.slice(startIndex), optionMetas);
+}
+export function installShellCompletion() {
+    const shell = detectShell();
+    const config = getShellConfig(shell);
+    if (shell === 'fish') {
+        installFishCompletion(config.rcFile);
+        return;
+    }
+    const { rcFile, sourceLine } = config;
+    if (fs.existsSync(rcFile)) {
+        const content = fs.readFileSync(rcFile, 'utf8');
+        if (content.includes(sourceLine)) {
+            console.log(`✅ 补全已存在于 ${rcFile}，无需重复安装`);
+            return;
+        }
+    }
+    fs.appendFileSync(rcFile, `\n# xfe shell completion\n${sourceLine}\n`);
+    console.log(`✅ 补全已安装到 ${rcFile}`);
+    console.log(`   请运行 \`source ${rcFile}\` 或重新打开终端以生效`);
+}
+export function uninstallShellCompletion() {
+    const shell = detectShell();
+    const config = getShellConfig(shell);
+    if (shell === 'fish') {
+        uninstallFishCompletion(config.rcFile);
+        return;
+    }
+    const { rcFile, sourceLine } = config;
+    if (!fs.existsSync(rcFile)) {
+        console.log(`⚠️  配置文件 ${rcFile} 不存在，无需卸载`);
+        return;
+    }
+    const original = fs.readFileSync(rcFile, 'utf8');
+    const cleaned = original
+        .split('\n')
+        .filter((line) => line !== sourceLine && line !== '# xfe shell completion')
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n');
+    if (original === cleaned) {
+        console.log(`⚠️  未在 ${rcFile} 中找到 xfe 补全配置，无需卸载`);
+        return;
+    }
+    fs.writeFileSync(rcFile, cleaned, 'utf8');
+    console.log(`✅ 补全已从 ${rcFile} 中移除`);
+}
+// ─── Helpers ────────────────────────────────────────────────
+function buildOptionFlags(meta) {
+    return meta.isBoolean ? `--${meta.name}` : `--${meta.name} <value>`;
+}
+function detectShell() {
+    const shell = process.env.SHELL ?? '';
+    if (shell.endsWith('zsh'))
+        return 'zsh';
+    if (shell.endsWith('bash'))
+        return 'bash';
+    if (shell.endsWith('fish'))
+        return 'fish';
+    return 'zsh';
+}
+function getShellConfig(shell) {
+    const home = os.homedir();
+    switch (shell) {
+        case 'zsh':
+            return {
+                rcFile: path.join(home, '.zshrc'),
+                sourceLine: 'source <(xfe complete zsh)',
+            };
+        case 'bash':
+            return {
+                rcFile: path.join(home, '.bashrc'),
+                sourceLine: 'source <(xfe complete bash)',
+            };
+        case 'fish':
+            return {
+                rcFile: path.join(home, '.config', 'fish', 'completions', 'xfe.fish'),
+                sourceLine: '',
+            };
+    }
+}
+function locateSegmentsTail(argv, segments) {
+    for (let index = 0; index <= argv.length - segments.length; index++) {
+        const matched = segments.every((segment, offset) => argv[index + offset] === segment);
+        if (matched)
+            return index + segments.length;
+    }
+    return argv.length;
+}
+function installFishCompletion(completionFile) {
+    const dir = path.dirname(completionFile);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    try {
+        const script = execSync('xfe complete fish', { encoding: 'utf8' });
+        fs.writeFileSync(completionFile, script, 'utf8');
+        console.log(`✅ Fish 补全已安装到 ${completionFile}`);
+    }
+    catch {
+        console.error('❌ 生成 fish 补全脚本失败，请确认 xfe 已正确安装');
+    }
+}
+function uninstallFishCompletion(completionFile) {
+    if (!fs.existsSync(completionFile)) {
+        console.log(`⚠️  Fish 补全文件 ${completionFile} 不存在，无需卸载`);
+        return;
+    }
+    fs.unlinkSync(completionFile);
+    console.log(`✅ Fish 补全文件 ${completionFile} 已删除`);
+}
+//# sourceMappingURL=shell.js.map

package/dist/completion-core.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @xfe-repo/cli - 补全核心（与 UI / shell 协议解耦）
+ *
+ * 集中维护：命令目录条目类型、查询/输入解析、option/value 建议计算、
+ * 已用 flag 过滤、命令寻址、prefilled 提取、模糊匹配。
+ *
+ * 调用方：
+ * - TUI Commands 组件复用全部能力（含模糊匹配 / 二级菜单 / 已用 flag 过滤）
+ * - shell / 其他入口可按需复用 catalog 与 option 建议部分，不依赖 UI
+ */
+import type { CommandOptionMeta } from './command.js';
+export type CommandCatalogItemType = 'command' | 'group' | 'back' | 'option' | 'value';
+export interface CommandCatalogItem {
+    readonly name: string;
+    readonly description: string;
+    readonly disabled?: boolean;
+    readonly type?: CommandCatalogItemType;
+    readonly children?: CommandCatalogItem[];
+    /** 命令支持的 options（仅 type=command 时有意义，用于 --key= 补全） */
+    readonly options?: readonly CommandOptionMeta[];
+}
+export interface ParsedQuery {
+    readonly activeGroup: CommandCatalogItem | null;
+    readonly subQuery: string;
+    readonly topQuery: string;
+}
+export type ExtrasMode = {
+    readonly kind: 'value';
+    readonly command: CommandCatalogItem;
+    readonly key: string;
+    readonly partial: string;
+    readonly values: readonly string[];
+} | {
+    readonly kind: 'name';
+    readonly command: CommandCatalogItem;
+    readonly partial: string;
+    readonly usedNames: ReadonlySet<string>;
+};
+/** 解析 query 是否进入二级菜单模式 */
+export declare function parseQuery(query: string, options: readonly CommandCatalogItem[]): ParsedQuery;
+/** 顶级查询过滤 + 评分排序 */
+export declare function filterTopLevel(options: readonly CommandCatalogItem[], query: string): CommandCatalogItem[];
+/** 二级子命令过滤：同时尝试匹配完整名和 action 名 */
+export declare function filterSubCommands(options: readonly CommandCatalogItem[], query: string): CommandCatalogItem[];
+/**
+ * 识别 `<cmd> [--k=v ...] [--partial]` 形式的输入，返回 extras 模式
+ *
+ * 末尾 `--key=` 进入 value 模式；`--key` / `--` / 空 进入 name 模式
+ */
+export declare function parseExtrasMode(rawQuery: string, options: readonly CommandCatalogItem[]): ExtrasMode | null;
+/** extras 模式建议项（option 名或枚举值） */
+export declare function buildExtrasSuggestions(mode: ExtrasMode): CommandCatalogItem[];
+/** extras 模式 Tab 补全：替换末尾未完成 token，或在末尾空格后追加新 flag */
+export declare function applyExtrasCompletion(input: string, mode: ExtrasMode, selected: string): string;
+/** 输入包含 flag 时尝试解析对应命令；不依赖命令是否声明 options，仅用于建议回显 */
+export declare function resolveMatchedCommandWithFlags(rawQuery: string, options: readonly CommandCatalogItem[]): CommandCatalogItem | null;
+/** Enter 提交时把 `/cmd --k1=v1 --k2 v2` 解析为命令 + prefilled */
+export declare function extractCommandAndPrefilled(input: string, options: readonly CommandCatalogItem[]): {
+    command: CommandCatalogItem | null;
+    prefilled: Record<string, string>;
+};
+/** 判断输入是否已经包含 `--flag` token */
+export declare function hasFlagToken(input: string): boolean;
+//# sourceMappingURL=completion-core.d.ts.map