@xfe-repo/cli 2.0.7 → 2.0.8

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @xfe-repo/cli
 
+## 2.0.8
+
+### Patch Changes
+
+- 优化环境切换
+- Updated dependencies
+  - @xfe-repo/cli-presets@2.0.4
+  - @xfe-repo/cli-core@2.0.4
+
 ## 2.0.7
 
 ### Patch Changes

package/dist/app.js

@@ -134,8 +134,8 @@ function AppInner({ runner, toast, scriptName }) {
         layer: KeymapLayer.Global,
     });
     // ── 菜单事件 ──
-    const handleSelect = useCallback((name) => {
-        sessionManager.startSession(name);
+    const handleSelect = useCallback((name, prefilled) => {
+        sessionManager.startSession(name, prefilled);
     }, [sessionManager]);
     /** 从命令面板提交非命令文本 → 检查是否有插件处理，未注册时 toast 提示 */
     const handleUserInput = useCallback((input) => {

package/dist/bin.js

@@ -7,11 +7,10 @@
  */
 import { createRequire } from 'node:module';
 import { Command } from 'commander';
-import { z } from 'zod';
 import { globalRegistry } from '@xfe-repo/cli-core';
 import { registerAllPresets } from '@xfe-repo/cli-presets';
 import { launch, quickInitRunner } from './launcher.js';
-import { initTabCompletion, installShellCompletion, uninstallShellCompletion } from './completion.js';
+import { applyCommandOptionMetas, attachEnumOptionValueCompletions, createDynamicCommandBinding, initTabCompletion, installShellCompletion, parsePrefilledFromArgv, uninstallShellCompletion, } from './completion/shell.js';
 const require = createRequire(import.meta.url);
 const { version: CLI_VERSION } = require('../package.json');
 // ============================================================
@@ -22,17 +21,21 @@ registerAllPresets((def) => globalRegistry.register(def));
 // 主流程
 // ============================================================
 async function main() {
-    const program = buildProgram();
+    const dynamicBindingsByScriptName = new Map();
+    const program = buildProgram(dynamicBindingsByScriptName);
     // ── 动态注册已初始化项目的命令为子命令 ──
-    await registerDynamicCommands(program);
-    // ── 自动补全 ──
-    initTabCompletion(program);
+    const dynamicCommands = await registerDynamicCommands(program);
+    syncDynamicBindings(dynamicBindingsByScriptName, dynamicCommands);
+    // ── 自动补全（必须在动态命令注册后）──
+    const completion = initTabCompletion(program);
+    attachEnumOptionValueCompletions(completion, dynamicCommands);
     // ── 默认行为（无子命令匹配时）→ 交互式菜单或快捷执行 ──
     program
         .argument('[scriptName]', '直接执行指定脚本')
         .allowUnknownOption()
         .action(async (scriptName) => {
-        const prefilled = parseExtraArgs(program.args.slice(scriptName ? 1 : 0));
+        const optionMetas = scriptName ? dynamicBindingsByScriptName.get(scriptName)?.optionMetas : undefined;
+        const prefilled = scriptName ? parsePrefilledFromArgv(process.argv, [scriptName], optionMetas) : {};
         await launch({
             projectRoot: process.cwd(),
             cliRoot: getCLIRoot(),
@@ -49,7 +52,7 @@ main().catch((err) => {
 // ============================================================
 // 程序构建
 // ============================================================
-function buildProgram() {
+function buildProgram(dynamicBindingsByScriptName) {
     const program = new Command('xfe');
     program
         .description(`xfe 项目脚手架 v${CLI_VERSION}`)
@@ -58,7 +61,7 @@ function buildProgram() {
         .helpCommand(false)
         .showHelpAfterError(true);
     // ── 静态子命令 ──
-    registerCommandSubcommands(program);
+    registerCommandSubcommands(program, dynamicBindingsByScriptName);
     registerProjectCommands(program);
     registerCompleteCommands(program);
     return program;
@@ -66,7 +69,7 @@ function buildProgram() {
 // ============================================================
 // 子命令注册
 // ============================================================
-function registerCommandSubcommands(program) {
+function registerCommandSubcommands(program, dynamicBindingsByScriptName) {
     const cmdGroup = program.command('command').helpCommand(false).description('命令管理');
     cmdGroup
         .command('list')
@@ -83,7 +86,8 @@ function registerCommandSubcommands(program) {
         .description('运行指定命令')
         .allowUnknownOption()
         .action(async (name) => {
-        const prefilled = parseExtraArgs(process.argv.slice(process.argv.indexOf(name) + 1));
+        const optionMetas = dynamicBindingsByScriptName.get(name)?.optionMetas;
+        const prefilled = parsePrefilledFromArgv(process.argv, ['command', 'run', name], optionMetas);
         await launch({
             projectRoot: process.cwd(),
             cliRoot: getCLIRoot(),
@@ -140,97 +144,61 @@ function registerCompleteCommands(program) {
 // 动态脚本命令
 // ============================================================
 /**
- * 将当前项目的可用命令注册为 Commander 子命令
+ * 将当前项目可用命令注册为 Commander 子命令，并返回补全绑定列表
  *
- * - 扁平命令（无 `:`）→ 注册为顶级子命令（xfe build）
- * - 命名空间命令（有 `:`）→ 按 namespace 分组注册为二级子命令（xfe aiRules sync）
+ * - 扁平命令（无 `:`）→ 顶级子命令（xfe build）
+ * - 命名空间命令（有 `:`）→ 二级子命令（xfe rules sync）
  */
 async function registerDynamicCommands(program) {
+    const result = [];
+    const runner = await safeQuickInit();
+    if (!runner)
+        return result;
+    const namespaceCache = new Map();
+    for (const def of runner.getCommands()) {
+        const binding = createDynamicCommandBinding(def);
+        const parent = binding.namespace ? getOrCreateNamespaceGroup(program, binding.namespace, namespaceCache) : program;
+        const exists = parent.commands.find((c) => c.name() === binding.action);
+        if (exists)
+            continue;
+        const cmd = parent.command(binding.action).summary(def.simpleDescription).description(def.description).allowUnknownOption();
+        applyCommandOptionMetas(cmd, binding.optionMetas);
+        cmd.action(() => runDynamicScript(binding));
+        result.push(binding);
+    }
+    return result;
+}
+/** 安全初始化 runner：项目未配置或加载失败时返回 null，不影响静态命令 */
+async function safeQuickInit() {
     try {
-        const runner = await quickInitRunner(process.cwd(), getCLIRoot());
-        if (!runner)
-            return;
-        const commands = runner.getCommands();
-        // 按 namespace 分组
-        const flat = [];
-        const namespaced = new Map();
-        for (const command of commands) {
-            const colonIndex = command.name.indexOf(':');
-            if (colonIndex > 0) {
-                const ns = command.name.slice(0, colonIndex);
-                const group = namespaced.get(ns) ?? [];
-                group.push(command);
-                namespaced.set(ns, group);
-            }
-            else {
-                flat.push(command);
-            }
-        }
-        for (const command of flat) {
-            registerSingleCommand(program, command);
-        }
-        for (const [ns, cmds] of namespaced) {
-            registerNamespaceCommands(program, ns, cmds);
-        }
+        return await quickInitRunner(process.cwd(), getCLIRoot());
     }
     catch {
-        // 初始化失败时（如配置损坏）静默跳过，不影响其他命令
+        return null;
     }
 }
-/** 注册命名空间子命令组（如 xfe aiRules sync / xfe aiRules list） */
-function registerNamespaceCommands(program, namespace, commands) {
-    // 避免与已有子命令冲突
+/** 复用或新建 namespace 命令组（如 `xfe rules`） */
+function getOrCreateNamespaceGroup(program, namespace, cache) {
+    const cached = cache.get(namespace);
+    if (cached)
+        return cached;
     const existing = program.commands.find((cmd) => cmd.name() === namespace);
-    if (existing)
-        return;
-    const group = program.command(namespace).helpCommand(false).description(`${namespace} 命令组`);
-    for (const command of commands) {
-        const action = command.name.slice(namespace.length + 1);
-        const sub = group.command(action).summary(command.simpleDescription).description(command.description).allowUnknownOption();
-        if (command.parameters && command.parameters instanceof z.ZodObject) {
-            const shape = command.parameters.shape;
-            for (const key of Object.keys(shape)) {
-                const description = shape[key].description ?? key;
-                sub.option(`--${key} <value>`, description);
-            }
-        }
-        sub.action(async () => {
-            const nsIndex = process.argv.indexOf(namespace);
-            const prefilled = parseExtraArgs(process.argv.slice(nsIndex + 2));
-            await launch({
-                projectRoot: process.cwd(),
-                cliRoot: getCLIRoot(),
-                scriptName: command.name,
-                prefilled,
-            });
-        });
+    if (existing) {
+        cache.set(namespace, existing);
+        return existing;
     }
+    const group = program.command(namespace).helpCommand(false).description(`${namespace} 命令组`);
+    cache.set(namespace, group);
+    return group;
 }
-function registerSingleCommand(program, command) {
-    // 避免与已有子命令冲突
-    const existing = program.commands.find((cmd) => cmd.name() === command.name);
-    if (existing)
-        return;
-    const cmd = program.command(command.name).summary(command.simpleDescription).description(command.description).allowUnknownOption();
-    // 如果定义了 parameters Schema，解析 Zod 字段类型和描述注册为 Commander options
-    if (command.parameters && command.parameters instanceof z.ZodObject) {
-        const zodObj = command.parameters;
-        const shape = zodObj.shape;
-        for (const key of Object.keys(shape)) {
-            const zodField = shape[key];
-            const description = zodField.description ?? key;
-            cmd.option(`--${key} <value>`, description);
-        }
-    }
-    cmd.action(async () => {
-        const nameIndex = process.argv.indexOf(command.name);
-        const prefilled = parseExtraArgs(process.argv.slice(nameIndex + 1));
-        await launch({
-            projectRoot: process.cwd(),
-            cliRoot: getCLIRoot(),
-            scriptName: command.name,
-            prefilled,
-        });
+/** 执行动态命令：用 fullName 段序列定位 argv 切片起点，避免 indexOf 误匹配 */
+async function runDynamicScript(binding) {
+    const prefilled = parsePrefilledFromArgv(process.argv, binding.tabName.split(' '), binding.optionMetas);
+    await launch({
+        projectRoot: process.cwd(),
+        cliRoot: getCLIRoot(),
+        scriptName: binding.scriptName,
+        prefilled,
     });
 }
 // ============================================================
@@ -240,24 +208,10 @@ function registerSingleCommand(program, command) {
 function getCLIRoot() {
     return new URL('..', import.meta.url).pathname;
 }
-/**
- * 解析额外的 --key value 参数
- *
- * 示例：xfe build --env test --test 11
- * 输出：{ env: 'test', test: '11' }
- */
-function parseExtraArgs(args) {
-    const result = {};
-    for (let i = 0; i < args.length; i++) {
-        const [curr, next] = [args[i], args[i + 1]];
-        // 只处理以 '--' 开头的参数
-        if (!curr.startsWith('--'))
-            continue;
-        const key = curr.slice(2);
-        // 下一个参数存在且不是 flag，那就是当前 key 的值
-        const hasValue = next && !next.startsWith('--');
-        result[key] = hasValue ? (i++, next) : 'true';
+function syncDynamicBindings(target, bindings) {
+    target.clear();
+    for (const binding of bindings) {
+        target.set(binding.scriptName, binding);
     }
-    return result;
 }
 //# sourceMappingURL=bin.js.map

package/dist/command-catalog.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @xfe-repo/cli - 命令目录构造（TUI / shell 共用的命令视图聚合）
+ *
+ * 把 core 的 CommandWithSource 列表转换为 completion-core 的 CommandCatalogItem 树
+ * - 同一 source 且共享 namespace 前缀的命令折叠为 group 项
+ * - 命令支持的 options 由 Zod parameters 派生（getCommandOptionsMeta）
+ * - 运行中命令标记为 disabled，描述加 `(运行中)` 前缀
+ */
+import type { CommandWithSource } from '@xfe-repo/cli-core';
+import type { CommandCatalogItem } from './completion-core.js';
+export interface BuildCatalogOptions {
+    /** 当前正在运行的命令名集合，用于禁用对应条目 */
+    readonly runningCommandNames?: ReadonlySet<string>;
+    /** 是否在末尾追加 exit 项（默认 true，TUI 使用） */
+    readonly includeExit?: boolean;
+}
+/** 构造命令目录：按 source 分组，namespace 命令折叠为 group */
+export declare function buildCommandCatalog(commandsWithSource: readonly CommandWithSource[], options?: BuildCatalogOptions): CommandCatalogItem[];
+//# sourceMappingURL=command-catalog.d.ts.map

package/dist/command-catalog.js

@@ -0,0 +1,67 @@
+/**
+ * @xfe-repo/cli - 命令目录构造（TUI / shell 共用的命令视图聚合）
+ *
+ * 把 core 的 CommandWithSource 列表转换为 completion-core 的 CommandCatalogItem 树
+ * - 同一 source 且共享 namespace 前缀的命令折叠为 group 项
+ * - 命令支持的 options 由 Zod parameters 派生（getCommandOptionsMeta）
+ * - 运行中命令标记为 disabled，描述加 `(运行中)` 前缀
+ */
+import { getCommandOptionsMeta, splitCommandName } from './command.js';
+/** 构造命令目录：按 source 分组，namespace 命令折叠为 group */
+export function buildCommandCatalog(commandsWithSource, options) {
+    const running = options?.runningCommandNames ?? new Set();
+    const includeExit = options?.includeExit ?? true;
+    const sourceGroups = groupBySource(commandsWithSource);
+    const items = [];
+    for (const entries of sourceGroups.values()) {
+        const namespacePrefix = detectSharedNamespace(entries);
+        if (namespacePrefix) {
+            const children = entries.map((e) => toCatalogItem(e, running));
+            items.push({
+                name: namespacePrefix,
+                description: `${children.length} 个命令`,
+                type: 'group',
+                children,
+            });
+            continue;
+        }
+        for (const entry of entries)
+            items.push(toCatalogItem(entry, running));
+    }
+    if (includeExit)
+        items.push({ name: 'exit', description: '退出 CLI' });
+    return items;
+}
+// ─── Helpers ────────────────────────────────────────────────
+function groupBySource(commandsWithSource) {
+    const groups = new Map();
+    for (const entry of commandsWithSource) {
+        const list = groups.get(entry.source) ?? [];
+        list.push(entry);
+        groups.set(entry.source, list);
+    }
+    return groups;
+}
+/** 检测一组命令是否共享同一个 namespace 前缀 */
+function detectSharedNamespace(entries) {
+    if (entries.length < 2)
+        return null;
+    const prefixes = entries.map((e) => splitCommandName(e.command.name).namespace);
+    const first = prefixes[0];
+    if (!first)
+        return null;
+    if (prefixes.every((p) => p === first))
+        return first;
+    return null;
+}
+function toCatalogItem(entry, running) {
+    const { name, simpleDescription } = entry.command;
+    const isRunning = running.has(name);
+    return {
+        name,
+        description: isRunning ? `(运行中) ${simpleDescription}` : simpleDescription,
+        disabled: isRunning,
+        options: getCommandOptionsMeta(entry.command.parameters),
+    };
+}
+//# sourceMappingURL=command-catalog.js.map

package/dist/command.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @xfe-repo/cli - 命令元数据 / 参数解析公用工具
+ *
+ * 集中三类职责：
+ * - 从命令 Zod parameters 提取 option 元数据（供 commander、TUI 补全、shell 补全共用）
+ * - 解析 `--key value` / `--key=value` / `--flag` 形式的命令 token 为 prefilled 对象
+ * - 拆分 `namespace:action` 形式的命令名
+ */
+export interface CommandOptionMeta {
+    readonly name: string;
+    readonly description: string;
+    readonly enumValues?: readonly string[];
+    /** 是否为开关型 option（boolean，无值） */
+    readonly isBoolean?: boolean;
+}
+export interface SplitCommandName {
+    readonly namespace: string | null;
+    readonly action: string;
+    readonly full: string;
+}
+/** 从命令的 Zod parameters 提取 option 元数据；非 ZodObject 或无字段时返回 undefined */
+export declare function getCommandOptionsMeta(parameters: unknown): CommandOptionMeta[] | undefined;
+/**
+ * 解析 `--key value` / `--key=value` / 裸 `--flag` 形式的命令 token 列表
+ *
+ * - 非 `--` 前缀的 token 直接跳过
+ * - 裸 flag 视为 `'true'`
+ * - 提供 metas 时，boolean 字段视为开关，下一 token 不会被消费
+ */
+export declare function parseCommandFlagTokens(tokens: readonly string[], metas?: readonly CommandOptionMeta[]): Record<string, string>;
+/** 按首个 `:` 拆分命令名；无冒号时 namespace 为 null */
+export declare function splitCommandName(name: string): SplitCommandName;
+/**
+ * 把 `<cmd...> [--flag ...]` 形式的查询拆分为命令 tokens 与 flag tokens
+ *
+ * - 以首个 `--token` 为分界，前面是命令部分（可能是 1~N 个 token）
+ * - `endsWithSpace` 用于补全场景区分「正在敲」与「敲完了」
+ * - 纯字符串拆分，不感知具体命令注册表
+ */
+export declare function splitFlagTokens(rawQuery: string): {
+    cmdTokens: string[];
+    flagTokens: string[];
+    endsWithSpace: boolean;
+} | null;
+//# sourceMappingURL=command.d.ts.map

package/dist/command.js

@@ -0,0 +1,88 @@
+/**
+ * @xfe-repo/cli - 命令元数据 / 参数解析公用工具
+ *
+ * 集中三类职责：
+ * - 从命令 Zod parameters 提取 option 元数据（供 commander、TUI 补全、shell 补全共用）
+ * - 解析 `--key value` / `--key=value` / `--flag` 形式的命令 token 为 prefilled 对象
+ * - 拆分 `namespace:action` 形式的命令名
+ */
+import { z } from 'zod';
+// ─── Public API ─────────────────────────────────────────────
+/** 从命令的 Zod parameters 提取 option 元数据；非 ZodObject 或无字段时返回 undefined */
+export function getCommandOptionsMeta(parameters) {
+    if (!(parameters instanceof z.ZodObject))
+        return undefined;
+    const shape = parameters.shape;
+    const result = [];
+    for (const [name, field] of Object.entries(shape)) {
+        const inner = unwrapOptional(field);
+        result.push({
+            name,
+            description: field.description ?? '',
+            enumValues: inner instanceof z.ZodEnum ? inner.options : undefined,
+            isBoolean: inner instanceof z.ZodBoolean ? true : undefined,
+        });
+    }
+    return result.length > 0 ? result : undefined;
+}
+/**
+ * 解析 `--key value` / `--key=value` / 裸 `--flag` 形式的命令 token 列表
+ *
+ * - 非 `--` 前缀的 token 直接跳过
+ * - 裸 flag 视为 `'true'`
+ * - 提供 metas 时，boolean 字段视为开关，下一 token 不会被消费
+ */
+export function parseCommandFlagTokens(tokens, metas) {
+    const result = {};
+    const byName = new Map();
+    for (const m of metas ?? [])
+        byName.set(m.name, m);
+    for (let i = 0; i < tokens.length; i++) {
+        const curr = tokens[i];
+        if (!curr.startsWith('--'))
+            continue;
+        const eq = curr.indexOf('=');
+        if (eq >= 0) {
+            result[curr.slice(2, eq)] = curr.slice(eq + 1);
+            continue;
+        }
+        const key = curr.slice(2);
+        const isBoolean = byName.get(key)?.isBoolean === true;
+        const next = tokens[i + 1];
+        const hasValue = !isBoolean && next && !next.startsWith('--');
+        result[key] = hasValue ? (i++, next) : 'true';
+    }
+    return result;
+}
+/** 按首个 `:` 拆分命令名；无冒号时 namespace 为 null */
+export function splitCommandName(name) {
+    const idx = name.indexOf(':');
+    if (idx <= 0)
+        return { namespace: null, action: name, full: name };
+    return { namespace: name.slice(0, idx), action: name.slice(idx + 1), full: name };
+}
+/**
+ * 把 `<cmd...> [--flag ...]` 形式的查询拆分为命令 tokens 与 flag tokens
+ *
+ * - 以首个 `--token` 为分界，前面是命令部分（可能是 1~N 个 token）
+ * - `endsWithSpace` 用于补全场景区分「正在敲」与「敲完了」
+ * - 纯字符串拆分，不感知具体命令注册表
+ */
+export function splitFlagTokens(rawQuery) {
+    const trimmedRight = rawQuery.replace(/\s+$/, '');
+    if (!trimmedRight)
+        return null;
+    const endsWithSpace = trimmedRight.length < rawQuery.length;
+    const tokens = trimmedRight.split(/\s+/);
+    const firstFlagIdx = tokens.findIndex((t) => t.startsWith('--'));
+    return {
+        cmdTokens: firstFlagIdx === -1 ? tokens : tokens.slice(0, firstFlagIdx),
+        flagTokens: firstFlagIdx === -1 ? [] : tokens.slice(firstFlagIdx),
+        endsWithSpace,
+    };
+}
+// ─── Helpers ────────────────────────────────────────────────
+function unwrapOptional(field) {
+    return field instanceof z.ZodOptional ? field.unwrap() : field;
+}
+//# sourceMappingURL=command.js.map

package/dist/completion/catalog.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @xfe-repo/cli - 命令目录构造（TUI / shell 共用的命令视图聚合）
+ */
+import type { CommandWithSource } from '@xfe-repo/cli-core';
+import type { CommandCatalogItem } from './core.js';
+export interface BuildCatalogOptions {
+    readonly runningCommandNames?: ReadonlySet<string>;
+    readonly includeExit?: boolean;
+}
+export declare function buildCommandCatalog(commandsWithSource: readonly CommandWithSource[], options?: BuildCatalogOptions): CommandCatalogItem[];
+//# sourceMappingURL=catalog.d.ts.map

package/dist/completion/catalog.js

@@ -0,0 +1,60 @@
+/**
+ * @xfe-repo/cli - 命令目录构造（TUI / shell 共用的命令视图聚合）
+ */
+import { getCommandOptionsMeta, splitCommandName } from './command.js';
+export function buildCommandCatalog(commandsWithSource, options) {
+    const running = options?.runningCommandNames ?? new Set();
+    const includeExit = options?.includeExit ?? true;
+    const sourceGroups = groupBySource(commandsWithSource);
+    const items = [];
+    for (const entries of sourceGroups.values()) {
+        const namespacePrefix = detectSharedNamespace(entries);
+        if (namespacePrefix) {
+            const children = entries.map((entry) => toCatalogItem(entry, running));
+            items.push({
+                name: namespacePrefix,
+                description: `${children.length} 个命令`,
+                type: 'group',
+                children,
+            });
+            continue;
+        }
+        for (const entry of entries)
+            items.push(toCatalogItem(entry, running));
+    }
+    if (includeExit)
+        items.push({ name: 'exit', description: '退出 CLI' });
+    return items;
+}
+// ─── Helpers ────────────────────────────────────────────────
+function groupBySource(commandsWithSource) {
+    const groups = new Map();
+    for (const entry of commandsWithSource) {
+        const list = groups.get(entry.source) ?? [];
+        list.push(entry);
+        groups.set(entry.source, list);
+    }
+    return groups;
+}
+function detectSharedNamespace(entries) {
+    if (entries.length < 2)
+        return null;
+    const prefixes = entries.map((entry) => splitCommandName(entry.command.name).namespace);
+    const first = prefixes[0];
+    if (!first)
+        return null;
+    if (prefixes.every((prefix) => prefix === first))
+        return first;
+    return null;
+}
+function toCatalogItem(entry, running) {
+    const { name, simpleDescription } = entry.command;
+    const isRunning = running.has(name);
+    return {
+        name,
+        description: isRunning ? `(运行中) ${simpleDescription}` : simpleDescription,
+        disabled: isRunning,
+        options: getCommandOptionsMeta(entry.command.parameters),
+    };
+}
+//# sourceMappingURL=catalog.js.map

package/dist/completion/command.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @xfe-repo/cli - 命令元数据 / 参数解析公用工具
+ *
+ * 集中三类职责：
+ * - 从命令 Zod parameters 提取 option 元数据（供 commander、TUI 补全、shell 补全共用）
+ * - 解析 `--key value` / `--key=value` / `--flag` 形式的命令 token 为 prefilled 对象
+ * - 拆分 `namespace:action` 形式的命令名
+ */
+export interface CommandOptionMeta {
+    readonly name: string;
+    readonly description: string;
+    readonly enumValues?: readonly string[];
+    /** 是否为开关型 option（boolean，无值） */
+    readonly isBoolean?: boolean;
+}
+export interface SplitCommandName {
+    readonly namespace: string | null;
+    readonly action: string;
+    readonly full: string;
+}
+/** 从命令的 Zod parameters 提取 option 元数据；非 ZodObject 或无字段时返回 undefined */
+export declare function getCommandOptionsMeta(parameters: unknown): CommandOptionMeta[] | undefined;
+/**
+ * 解析 `--key value` / `--key=value` / 裸 `--flag` 形式的命令 token 列表
+ *
+ * - 非 `--` 前缀的 token 直接跳过
+ * - 裸 flag 视为 `'true'`
+ * - 提供 metas 时，boolean 字段视为开关，下一 token 不会被消费
+ */
+export declare function parseCommandFlagTokens(tokens: readonly string[], metas?: readonly CommandOptionMeta[]): Record<string, string>;
+/** 按首个 `:` 拆分命令名；无冒号时 namespace 为 null */
+export declare function splitCommandName(name: string): SplitCommandName;
+/**
+ * 把 `<cmd...> [--flag ...]` 形式的查询拆分为命令 tokens 与 flag tokens
+ *
+ * - 以首个 `--token` 为分界，前面是命令部分（可能是 1~N 个 token）
+ * - `endsWithSpace` 用于补全场景区分「正在敲」与「敲完了」
+ * - 纯字符串拆分，不感知具体命令注册表
+ */
+export declare function splitFlagTokens(rawQuery: string): {
+    cmdTokens: string[];
+    flagTokens: string[];
+    endsWithSpace: boolean;
+} | null;
+//# sourceMappingURL=command.d.ts.map