🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
/**
* V3 CLI Command Parser
* Advanced argument parsing with validation and type coercion
*/
import type { Command, CommandOption, ParsedFlags, CommandContext, V3Config } from './types.js';
export interface ParseResult {
command: string[];
flags: ParsedFlags;
positional: string[];
raw: string[];
}
export interface ParserOptions {
stopAtFirstNonFlag?: boolean;
allowUnknownFlags?: boolean;
booleanFlags?: string[];
stringFlags?: string[];
arrayFlags?: string[];
aliases?: Record<string, string>;
defaults?: Record<string, unknown>;
}
export class CommandParser {
private options: ParserOptions;
private commands: Map<string, Command> = new Map();
private lazyCommandNames: Set<string> = new Set();
private globalOptions: CommandOption[] = [];
constructor(options: ParserOptions = {}) {
this.options = {
stopAtFirstNonFlag: false,
allowUnknownFlags: false,
...options
};
this.initializeGlobalOptions();
}
private initializeGlobalOptions(): void {
this.globalOptions = [
{
name: 'help',
short: 'h',
description: 'Show help information',
type: 'boolean',
default: false
},
{
name: 'version',
short: 'V',
description: 'Show version number',
type: 'boolean',
default: false
},
{
name: 'verbose',
short: 'v',
description: 'Enable verbose output',
type: 'boolean',
default: false
},
{
name: 'quiet',
short: 'Q',
description: 'Suppress non-essential output',
type: 'boolean',
default: false
},
{
name: 'config',
short: 'c',
description: 'Path to configuration file',
type: 'string'
},
{
name: 'format',
// Note: removed global short flag 'f' — it collides with 50+ subcommand
// flags (force, follow, file, feature, full) causing unpredictable behavior
// depending on parser resolution order (#1425). Use --format instead.
description: 'Output format (text, json, table)',
type: 'string',
default: 'text',
choices: ['text', 'json', 'table']
},
{
name: 'no-color',
description: 'Disable colored output',
type: 'boolean',
default: false
},
{
name: 'interactive',
short: 'i',
description: 'Enable interactive mode',
type: 'boolean',
default: true
}
];
}
registerCommand(command: Command): void {
this.commands.set(command.name, command);
if (command.aliases) {
for (const alias of command.aliases) {
this.commands.set(alias, command);
}
}
}
/**
* Register a lazy-loaded command's name so Pass 1/Pass 2 can recognize it as
* a command position even though its full definition hasn't been loaded yet.
* Fix for #1596: without this, lazy commands like `daemon start` were
* mis-routed because Pass 1 walked past `daemon` and greedy-matched `start`.
*/
registerLazyCommandName(name: string): void {
this.lazyCommandNames.add(name);
}
/**
* #1791.2 — true when `name` is a lazy command that hasn't been promoted
* to a fully registered Command yet. The CLI uses this to eagerly load
* the module before parsing so its subcommand flags (e.g. `-d` for
* `hive-mind task --description`) are scoped into the alias map. Without
* this, lazy commands' short flags silently fall through to global
* resolution and the action handler sees an empty `flags.description`.
*/
isLazyOnly(name: string): boolean {
return this.lazyCommandNames.has(name) && !this.commands.has(name);
}
private isKnownCommandName(name: string): boolean {
return this.commands.has(name) || this.lazyCommandNames.has(name);
}
getCommand(name: string): Command | undefined {
return this.commands.get(name);
}
getAllCommands(): Command[] {
// Return unique commands (filter out aliases)
const seen = new Set<Command>();
return Array.from(this.commands.values()).filter(cmd => {
if (seen.has(cmd)) return false;
seen.add(cmd);
return true;
});
}
parse(args: string[]): ParseResult {
const result: ParseResult = {
command: [],
flags: { _: [] },
positional: [],
raw: [...args]
};
// Pass 1: Identify command and subcommand (skip flags).
// Fix for #1596: the first non-flag positional is ALWAYS the command slot.
// If it's a known command (sync or lazy) we resolve it; otherwise we stop
// searching — we MUST NOT walk past it and greedy-match a later arg as the
// command, because that's what caused `daemon start` to resolve as `start`
// with `daemon` left as a positional.
let resolvedCmd: Command | undefined;
const resolvedCommands: Command[] = [];
let sawFirstPositional = false;
for (let index = 0; index < args.length; index++) {
const arg = args[index];
if (arg === '--') break;
if (arg.startsWith('-')) {
// Pass 2 recognizes only contiguous subcommands after the root.
if (sawFirstPositional) break;
// Skip consumed values as well as flags: a global option value is not
// the command slot, even when it happens to name another command.
const scope = this.getFlagScope(resolvedCommands);
index = this.parseFlag(args, index, scope.aliases, scope.booleanFlags, scope.stringFlags).nextIndex - 1;
continue;
}
if (!sawFirstPositional) {
sawFirstPositional = true;
if (this.commands.has(arg)) {
resolvedCmd = this.commands.get(arg)!;
resolvedCommands.push(resolvedCmd);
continue;
}
// Lazy command: we know its name but not its subcommands. Stop the
// walk here — we'll rely on Pass 2 to push it onto commandPath.
if (this.lazyCommandNames.has(arg)) {
break;
}
// Unknown first positional — not a command. Stop walking.
break;
}
// Match the same supported command depth as Pass 2, with each option
// declaration taking precedence over its parent scope.
const parent = resolvedCommands[resolvedCommands.length - 1];
if (resolvedCommands.length < 4 && parent?.subcommands) {
const child = parent.subcommands.find(sc => sc.name === arg || sc.aliases?.includes(arg));
if (child) {
resolvedCommands.push(child);
continue;
}
}
// A positional that is not the next subcommand ends the command path.
break;
}
const { aliases, booleanFlags, stringFlags, arrayFlags } = this.getFlagScope(resolvedCommands);
let i = 0;
let parsingFlags = true;
let commandSlotAvailable = true;
while (i < args.length) {
const arg = args[i];
// Check for end of flags marker. Only the first "--" changes parser
// state; a later literal "--" is an ordinary positional (#4310).
if (parsingFlags && arg === '--') {
parsingFlags = false;
i++;
continue;
}
// Handle flags
if (parsingFlags && arg.startsWith('-')) {
const parseResult = this.parseFlag(args, i, aliases, booleanFlags, stringFlags);
// Array declarations retain text and accumulate repeated occurrences.
for (const key of arrayFlags) {
const value = parseResult.flags[key];
if (value !== undefined && value !== true && value !== false) {
const previous = result.flags[key];
parseResult.flags[key] = [...(Array.isArray(previous) ? previous : []), String(value)];
}
}
// Apply to result flags
const { _: ignoredPositionals, ...parsedFlags } = parseResult.flags;
Object.assign(result.flags, parsedFlags);
i = parseResult.nextIndex;
continue;
}
// Handle positional arguments.
// Fix for #1596: treat lazy command names as commands here too so that
// downstream dispatch sees `commandPath = ['daemon', 'start']` instead of
// `commandPath = ['start'], positional = ['daemon']`.
const isCommandSlot = commandSlotAvailable && parsingFlags;
commandSlotAvailable = false;
if (isCommandSlot && this.isKnownCommandName(arg)) {
// This is a command
result.command.push(arg);
// Check for subcommand (level 1) — only possible for sync commands
// whose subcommand definitions are already loaded.
const cmd = this.commands.get(arg);
if (cmd?.subcommands && i + 1 < args.length) {
const nextArg = args[i + 1];
const subCmd = cmd.subcommands.find(sc => sc.name === nextArg || sc.aliases?.includes(nextArg));
if (subCmd) {
result.command.push(nextArg);
i++;
// Check for nested subcommand (level 2)
if (subCmd.subcommands && i + 1 < args.length) {
const nestedArg = args[i + 1];
const nestedCmd = subCmd.subcommands.find(sc => sc.name === nestedArg || sc.aliases?.includes(nestedArg));
if (nestedCmd) {
result.command.push(nestedArg);
i++;
// Check for deeply nested subcommand (level 3)
if (nestedCmd.subcommands && i + 1 < args.length) {
const deepArg = args[i + 1];
const deepCmd = nestedCmd.subcommands.find(sc => sc.name === deepArg || sc.aliases?.includes(deepArg));
if (deepCmd) {
result.command.push(deepArg);
i++;
}
}
}
}
}
}
} else {
// Positional argument
result.positional.push(arg);
result.flags._.push(arg);
}
i++;
}
// Apply defaults (globals + resolved command/subcommand — #2775 follow-up).
// Previously only globals were walked, so any subcommand-declared
// `default: true` silently dropped and reached the action handler as
// `undefined`. That trapped `memory store --upsert` and every other
// subcommand that leaned on a per-flag default.
this.applyDefaults(result.flags, resolvedCommands);
return result;
}
private parseFlag(
args: string[],
index: number,
aliases: Record<string, string>,
booleanFlags: Set<string>,
stringFlags: Set<string>
): { flags: ParsedFlags; nextIndex: number } {
const flags: ParsedFlags = { _: [] };
const arg = args[index];
let nextIndex = index + 1;
if (arg.startsWith('--')) {
// Long flag
const equalIndex = arg.indexOf('=');
if (equalIndex !== -1) {
// --flag=value
const key = arg.slice(2, equalIndex);
const value = arg.slice(equalIndex + 1);
const normalizedKey = this.normalizeKey(key);
flags[normalizedKey] = stringFlags.has(normalizedKey) ? value : this.parseValue(value);
} else if (arg.startsWith('--no-')) {
// --no-flag (boolean negation)
const key = arg.slice(5);
flags[this.normalizeKey(key)] = false;
} else {
const key = arg.slice(2);
const normalizedKey = this.normalizeKey(key);
if (booleanFlags.has(normalizedKey)) {
// #explore-flag: allow an explicit boolean value (`--explore false`,
// `--explore true`). Without this, a default-true boolean could never
// be disabled via the space form — the value was dropped and the flag
// forced to true. The `=` form already worked via parseValue.
if (nextIndex < args.length && this.isBooleanLiteral(args[nextIndex])) {
flags[normalizedKey] = args[nextIndex].toLowerCase() === 'true';
nextIndex++;
} else {
flags[normalizedKey] = true;
}
} else if (nextIndex < args.length && this.isFlagValue(args[nextIndex])) {
flags[normalizedKey] = stringFlags.has(normalizedKey) ? args[nextIndex] : this.parseValue(args[nextIndex]);
nextIndex++;
} else {
flags[normalizedKey] = true;
}
}
} else if (arg.startsWith('-')) {
// Short flag(s)
const chars = arg.slice(1);
if (chars.length === 1) {
// Single short flag
const key = aliases[chars] || chars;
const normalizedKey = this.normalizeKey(key);
if (booleanFlags.has(normalizedKey)) {
// #explore-flag: short boolean flags also accept an explicit value
// (`-e false`) so a default-true boolean can be turned off.
if (nextIndex < args.length && this.isBooleanLiteral(args[nextIndex])) {
flags[normalizedKey] = args[nextIndex].toLowerCase() === 'true';
nextIndex++;
} else {
flags[normalizedKey] = true;
}
} else if (nextIndex < args.length && this.isFlagValue(args[nextIndex])) {
flags[normalizedKey] = stringFlags.has(normalizedKey) ? args[nextIndex] : this.parseValue(args[nextIndex]);
nextIndex++;
} else {
flags[normalizedKey] = true;
}
} else {
// Multiple short flags combined (e.g., -abc)
for (const char of chars) {
const key = aliases[char] || char;
flags[this.normalizeKey(key)] = true;
}
}
}
return { flags, nextIndex };
}
/**
* Decide whether `arg` should be consumed as the VALUE of the preceding flag,
* rather than treated as the next flag.
*
* Bug fix (audit #1, follow-up to #2222): a negative numeric value such as
* `-1.0` starts with '-', so the old `!arg.startsWith('-')` test rejected it
* as a value and parsed it as a (bogus) short flag. For `route feedback
* -r -1.0` this silently dropped the value and coerced reward to `true` → 1.0,
* so NEGATIVE feedback REINFORCED the agent. Only `--reward=-1.0` worked.
*
* Anything not starting with '-' is a value (unchanged). Anything that starts
* with '-' is a value ONLY if it is a pure negative number (e.g. `-1`, `-1.0`,
* `-3.14`, `-1e3`). Real flags like `-r`, `--reward`, `-abc` are never numeric
* after the leading dash, so they are still correctly treated as flags.
*/
private isFlagValue(arg: string): boolean {
if (!arg.startsWith('-')) return true;
// Negative number: '-' followed by a parseable numeric literal.
return /^-\d*\.?\d+(?:[eE][+-]?\d+)?$/.test(arg);
}
/** True for the literal tokens `true`/`false` (case-insensitive). Used so a
* boolean flag can take an explicit value in the space form, e.g.
* `--explore false` / `-e true`. */
private isBooleanLiteral(arg: string): boolean {
const a = arg.toLowerCase();
return a === 'true' || a === 'false';
}
private parseValue(value: string): string | number | boolean {
// Boolean
if (value.toLowerCase() === 'true') return true;
if (value.toLowerCase() === 'false') return false;
// Number
const num = Number(value);
if (!isNaN(num) && value.trim() !== '') return num;
// String
return value;
}
private normalizeKey(key: string): string {
// Convert kebab-case to camelCase
return key.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
}
private buildAliases(): Record<string, string> {
const aliases: Record<string, string> = {};
for (const opt of this.globalOptions) {
if (opt.short) {
aliases[opt.short] = opt.name;
}
}
// Add aliases from all commands and subcommands
for (const cmd of this.commands.values()) {
if (cmd.options) {
for (const opt of cmd.options) {
if (opt.short) {
aliases[opt.short] = opt.name;
}
}
}
// Also include subcommands' options
if (cmd.subcommands) {
for (const sub of cmd.subcommands) {
if (sub.options) {
for (const opt of sub.options) {
if (opt.short) {
aliases[opt.short] = opt.name;
}
}
}
}
}
}
return { ...aliases, ...this.options.aliases };
}
/**
* Build aliases scoped to a specific command/subcommand.
* The resolved command's short flags take priority over global ones,
* fixing collisions where multiple subcommands use the same short flag (e.g. -t).
*/
private buildScopedAliases(resolvedCmd?: Command): Record<string, string> {
// Start with global aliases as base
const aliases = this.buildAliases();
// Override with the resolved command's own options (these take priority)
if (resolvedCmd?.options) {
for (const opt of resolvedCmd.options) {
if (opt.short) {
aliases[opt.short] = opt.name;
}
}
}
return aliases;
}
/**
* Get boolean flags scoped to a specific command/subcommand.
*
* `getBooleanFlags()` walks EVERY command + subcommand in the registry
* and adds their boolean options into one flat set. That's convenient
* for the common case but causes cross-subcommand pollution: if `swarm
* start --parallel` is boolean AND `hooks route --parallel` is numeric,
* the flat set marks `parallel` as boolean, and `hooks route --parallel 7`
* drops the `7` as a positional (parseFlag treats booleanFlags-hit as
* "consume no value"). This is the exact bug that forced the
* --moa-parallel rename in the 2026-07-26 dream-cycle #2778 fix.
*
* Fix: if the resolved subcommand declares the flag as a non-boolean
* type, REMOVE it from the boolean set. Narrowest scope wins.
* (Documented via in-tree comment in commands/hooks.ts and the #2778
* commit message.)
*/
private getScopedBooleanFlags(resolvedCmd?: Command): Set<string> {
const flags = this.getBooleanFlags();
if (resolvedCmd?.options) {
for (const opt of resolvedCmd.options) {
const key = this.normalizeKey(opt.name);
if (opt.type === 'boolean') {
flags.add(key);
} else if (opt.type) {
// Subcommand explicitly re-declares this flag as a non-boolean
// type (string/number/array) — narrowest scope wins, so drop
// it from the boolean set to override any global pollution.
flags.delete(key);
}
}
}
return flags;
}
/** Resolve declared types from broad to narrow without borrowing string
* declarations from unrelated registered commands. */
private getFlagScope(commands: Command[]): {
aliases: Record<string, string>;
booleanFlags: Set<string>;
stringFlags: Set<string>;
arrayFlags: Set<string>;
} {
const aliases = this.buildScopedAliases(commands[commands.length - 1]);
const booleanFlags = this.getScopedBooleanFlags(commands[commands.length - 1]);
const stringFlags = new Set((this.options.stringFlags ?? []).map(flag => this.normalizeKey(flag)));
for (const command of commands) {
for (const option of command.options ?? []) {
if (option.short) aliases[option.short] = option.name;
}
}
const arrayFlags = new Set((this.options.arrayFlags ?? []).map(flag => this.normalizeKey(flag)));
for (const flag of arrayFlags) stringFlags.add(flag);
const layers = [this.globalOptions, ...commands.map(command => command.options ?? [])];
for (const options of layers) {
for (const option of options) {
const key = this.normalizeKey(option.name);
if (option.type === 'array') arrayFlags.add(key);
else if (option.type) arrayFlags.delete(key);
if (option.type === 'string' || option.type === 'array') stringFlags.add(key);
else if (option.type) stringFlags.delete(key);
if (option.type === 'boolean') booleanFlags.add(key);
else if (option.type) booleanFlags.delete(key);
}
}
for (const flag of stringFlags) booleanFlags.delete(flag);
return { aliases, booleanFlags, stringFlags, arrayFlags };
}
private getBooleanFlags(): Set<string> {
const flags = new Set<string>();
for (const opt of this.globalOptions) {
if (opt.type === 'boolean') {
flags.add(this.normalizeKey(opt.name));
}
}
// Add boolean flags from all commands and subcommands
for (const cmd of this.commands.values()) {
if (cmd.options) {
for (const opt of cmd.options) {
if (opt.type === 'boolean') {
flags.add(this.normalizeKey(opt.name));
}
}
}
// Also include subcommands' boolean flags
if (cmd.subcommands) {
for (const sub of cmd.subcommands) {
if (sub.options) {
for (const opt of sub.options) {
if (opt.type === 'boolean') {
flags.add(this.normalizeKey(opt.name));
}
}
}
}
}
}
if (this.options.booleanFlags) {
for (const flag of this.options.booleanFlags) {
flags.add(this.normalizeKey(flag));
}
}
return flags;
}
private applyDefaults(flags: ParsedFlags, commands: Command[]): void {
// Walk every resolved command from narrow to broad so nested defaults
// have the same precedence as their declared flag types.
const layers = [...commands].reverse().map(command => command.options ?? []);
layers.push(this.globalOptions);
for (const layer of layers) {
for (const opt of layer) {
const key = this.normalizeKey(opt.name);
if (flags[key] === undefined && opt.default !== undefined) {
flags[key] = (Array.isArray(opt.default) ? [...opt.default] : opt.default) as string | boolean | number | string[];
}
}
}
// Apply custom defaults (lowest precedence)
if (this.options.defaults) {
for (const [key, value] of Object.entries(this.options.defaults)) {
const normalizedKey = this.normalizeKey(key);
if (flags[normalizedKey] === undefined) {
flags[normalizedKey] = (Array.isArray(value) ? [...value] : value) as string | boolean | number | string[];
}
}
}
}
validateFlags(flags: ParsedFlags, command?: Command): string[] {
const errors: string[] = [];
const allOptions = [...this.globalOptions];
if (command?.options) {
allOptions.push(...command.options);
}
// Check required flags
for (const opt of allOptions) {
const key = this.normalizeKey(opt.name);
if (opt.required && (flags[key] === undefined || flags[key] === '')) {
errors.push(`Required option missing: --${opt.name}`);
}
// A value-taking option given with nothing after it (`--task`, `--key` at the end, or
// followed by another flag) is parsed as boolean `true`. Commands then treat `true` as
// the value: `hooks route --task` crashed with "task.trim is not a function" and
// `memory retrieve --key` looked up the key "true". Report it instead.
if ((opt.type === 'string' || opt.type === 'number' || opt.type === 'array') && flags[key] === true) {
errors.push(`Option --${opt.name} needs a value`);
}
// Check choices
if (opt.choices && flags[key] !== undefined) {
const value = String(flags[key]);
if (!opt.choices.includes(value)) {
errors.push(`Invalid value for --${opt.name}: ${value}. Must be one of: ${opt.choices.join(', ')}`);
}
}
// Run custom validator
if (opt.validate && flags[key] !== undefined) {
const result = opt.validate(flags[key]);
if (result !== true) {
errors.push(typeof result === 'string' ? result : `Invalid value for --${opt.name}`);
}
}
}
// Check for unknown flags if not allowed
if (!this.options.allowUnknownFlags) {
const knownFlags = new Set(allOptions.map(opt => this.normalizeKey(opt.name)));
knownFlags.add('_'); // Positional args
for (const key of Object.keys(flags)) {
if (!knownFlags.has(key) && key !== '_') {
errors.push(`Unknown option: --${key}`);
}
}
}
return errors;
}
getGlobalOptions(): CommandOption[] {
return [...this.globalOptions];
}
}
// Export singleton parser instance
export const commandParser = new CommandParser({ allowUnknownFlags: true });