zouroboros-core 2.0.0

package/dist/commands.js

@@ -0,0 +1,307 @@
+/**
+ * ECC-002: Slash Commands Hub
+ *
+ * First-class CLI-style commands callable from any persona conversation.
+ * Zero-dependency command parser with unified help, registration, and routing.
+ * Supports subcommands: /memory search "query" → routes to memory.search handler.
+ */
+export class CommandHub {
+    commands = new Map();
+    aliases = new Map();
+    hooks = null;
+    /** Wire to hook system for command.execute events */
+    wireHooks(hooks) {
+        this.hooks = hooks;
+    }
+    register(definition) {
+        if (!definition.name || !definition.name.startsWith('/')) {
+            throw new Error(`Command name must start with '/': ${definition.name}`);
+        }
+        // Check for alias collisions
+        for (const alias of definition.aliases) {
+            const existing = this.aliases.get(alias);
+            if (existing && existing !== definition.name) {
+                throw new Error(`Alias '${alias}' already registered to '${existing}', cannot register for '${definition.name}'`);
+            }
+        }
+        this.commands.set(definition.name, definition);
+        for (const alias of definition.aliases) {
+            this.aliases.set(alias, definition.name);
+        }
+    }
+    /** Register a subcommand under an existing command */
+    registerSubcommand(commandName, sub) {
+        const cmd = this.commands.get(commandName);
+        if (!cmd)
+            throw new Error(`Command '${commandName}' not found`);
+        if (!cmd.subcommands)
+            cmd.subcommands = new Map();
+        cmd.subcommands.set(sub.name, sub);
+    }
+    unregister(name) {
+        const cmd = this.commands.get(name);
+        if (!cmd)
+            return false;
+        for (const alias of cmd.aliases) {
+            this.aliases.delete(alias);
+        }
+        this.commands.delete(name);
+        return true;
+    }
+    resolve(nameOrAlias) {
+        const cmd = this.commands.get(nameOrAlias);
+        if (cmd)
+            return cmd;
+        const canonical = this.aliases.get(nameOrAlias);
+        if (canonical)
+            return this.commands.get(canonical) || null;
+        return null;
+    }
+    parse(input) {
+        const trimmed = input.trim();
+        if (!trimmed.startsWith('/'))
+            return null;
+        const parts = this.tokenize(trimmed);
+        if (parts.length === 0)
+            return null;
+        const name = parts[0];
+        const args = {};
+        const flags = new Set();
+        let subcommand;
+        const def = this.resolve(name);
+        // Check for subcommand: if part[1] exists and matches a registered subcommand
+        let argDefs = def?.args || [];
+        let partStart = 1;
+        if (def?.subcommands && parts.length > 1 && def.subcommands.has(parts[1])) {
+            subcommand = parts[1];
+            argDefs = def.subcommands.get(parts[1]).args;
+            partStart = 2;
+        }
+        let positionalIndex = 0;
+        for (let i = partStart; i < parts.length; i++) {
+            const part = parts[i];
+            if (part.startsWith('--')) {
+                const key = part.slice(2);
+                const eqIdx = key.indexOf('=');
+                if (eqIdx >= 0) {
+                    args[key.slice(0, eqIdx)] = key.slice(eqIdx + 1);
+                }
+                else {
+                    const argDef = argDefs.find(a => a.name === key);
+                    if (argDef?.type === 'flag' || argDef?.type === 'boolean') {
+                        flags.add(key);
+                        args[key] = true;
+                    }
+                    else if (i + 1 < parts.length && !parts[i + 1].startsWith('--')) {
+                        args[key] = this.coerceArg(parts[++i], argDef?.type);
+                    }
+                    else {
+                        flags.add(key);
+                        args[key] = true;
+                    }
+                }
+            }
+            else {
+                const positionalDefs = argDefs.filter(a => a.type !== 'flag');
+                if (positionalIndex < positionalDefs.length) {
+                    const argDef = positionalDefs[positionalIndex];
+                    args[argDef.name] = this.coerceArg(part, argDef.type);
+                }
+                else {
+                    args[`_${positionalIndex}`] = part;
+                }
+                positionalIndex++;
+            }
+        }
+        // Apply defaults
+        for (const argDef of argDefs) {
+            if (argDef.default !== undefined && args[argDef.name] === undefined) {
+                args[argDef.name] = argDef.default;
+            }
+        }
+        return { name, subcommand, args, raw: trimmed, flags };
+    }
+    async execute(input) {
+        const parsed = this.parse(input);
+        if (!parsed) {
+            return { success: false, output: '', error: 'Invalid command format. Commands must start with /' };
+        }
+        const cmd = this.resolve(parsed.name);
+        if (!cmd) {
+            const suggestions = this.suggest(parsed.name);
+            const suggestionText = suggestions.length > 0
+                ? ` Did you mean: ${suggestions.join(', ')}?`
+                : '';
+            return { success: false, output: '', error: `Unknown command: ${parsed.name}.${suggestionText}` };
+        }
+        // Route to subcommand handler if applicable
+        let handler = cmd.handler;
+        let requiredArgs = cmd.args;
+        if (parsed.subcommand && cmd.subcommands?.has(parsed.subcommand)) {
+            const sub = cmd.subcommands.get(parsed.subcommand);
+            handler = sub.handler;
+            requiredArgs = sub.args;
+        }
+        // Validate required args
+        for (const argDef of requiredArgs) {
+            if (argDef.required && parsed.args[argDef.name] === undefined) {
+                return {
+                    success: false,
+                    output: '',
+                    error: `Missing required argument: ${argDef.name}\nUsage: ${cmd.usage}`,
+                };
+            }
+        }
+        try {
+            const result = await handler(parsed);
+            // Emit command.execute hook event
+            if (this.hooks) {
+                this.hooks.emit('command.execute', {
+                    command: parsed.name,
+                    subcommand: parsed.subcommand,
+                    success: result.success,
+                }, 'command-hub').catch(() => { });
+            }
+            return result;
+        }
+        catch (err) {
+            return {
+                success: false,
+                output: '',
+                error: `Command failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    help(commandName) {
+        if (commandName) {
+            const cmd = this.resolve(commandName);
+            if (!cmd)
+                return `Unknown command: ${commandName}`;
+            const lines = [
+                `${cmd.name} — ${cmd.description}`,
+                `Usage: ${cmd.usage}`,
+            ];
+            if (cmd.aliases.length > 0) {
+                lines.push(`Aliases: ${cmd.aliases.join(', ')}`);
+            }
+            if (cmd.subcommands && cmd.subcommands.size > 0) {
+                lines.push('Subcommands:');
+                for (const [subName, sub] of cmd.subcommands) {
+                    lines.push(`  ${subName} — ${sub.description}`);
+                }
+            }
+            if (cmd.args.length > 0) {
+                lines.push('Arguments:');
+                for (const arg of cmd.args) {
+                    const req = arg.required ? '(required)' : `(default: ${arg.default ?? 'none'})`;
+                    lines.push(`  --${arg.name}  ${arg.description} ${req}`);
+                }
+            }
+            return lines.join('\n');
+        }
+        // List all commands by category
+        const byCategory = new Map();
+        for (const cmd of this.commands.values()) {
+            if (cmd.hidden)
+                continue;
+            const list = byCategory.get(cmd.category) || [];
+            list.push(cmd);
+            byCategory.set(cmd.category, list);
+        }
+        const lines = ['Available Commands:', ''];
+        for (const [category, cmds] of byCategory) {
+            lines.push(`[${category}]`);
+            for (const cmd of cmds.sort((a, b) => a.name.localeCompare(b.name))) {
+                const aliasStr = cmd.aliases.length > 0 ? ` (${cmd.aliases.join(', ')})` : '';
+                lines.push(`  ${cmd.name}${aliasStr} — ${cmd.description}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    suggest(partial) {
+        const lower = partial.toLowerCase();
+        const matches = [];
+        for (const name of this.commands.keys()) {
+            if (name.toLowerCase().includes(lower) || this.levenshtein(name.toLowerCase(), lower) <= 2) {
+                matches.push(name);
+            }
+        }
+        for (const [alias, canonical] of this.aliases) {
+            if (alias.toLowerCase().includes(lower)) {
+                matches.push(`${alias} → ${canonical}`);
+            }
+        }
+        return matches.slice(0, 5);
+    }
+    list(category) {
+        const all = [...this.commands.values()];
+        if (category)
+            return all.filter(c => c.category === category);
+        return all;
+    }
+    getCategories() {
+        const counts = {};
+        for (const cmd of this.commands.values()) {
+            counts[cmd.category] = (counts[cmd.category] || 0) + 1;
+        }
+        return counts;
+    }
+    tokenize(input) {
+        const tokens = [];
+        let current = '';
+        let inQuote = false;
+        let quoteChar = '';
+        for (const ch of input) {
+            if (inQuote) {
+                if (ch === quoteChar) {
+                    inQuote = false;
+                }
+                else {
+                    current += ch;
+                }
+            }
+            else if (ch === '"' || ch === "'") {
+                inQuote = true;
+                quoteChar = ch;
+            }
+            else if (ch === ' ' || ch === '\t') {
+                if (current.length > 0) {
+                    tokens.push(current);
+                    current = '';
+                }
+            }
+            else {
+                current += ch;
+            }
+        }
+        if (current.length > 0)
+            tokens.push(current);
+        return tokens;
+    }
+    coerceArg(value, type) {
+        if (type === 'number') {
+            const n = Number(value);
+            return isNaN(n) ? value : n;
+        }
+        if (type === 'boolean') {
+            return value === 'true' || value === '1' || value === 'yes';
+        }
+        return value;
+    }
+    levenshtein(a, b) {
+        const m = a.length, n = b.length;
+        const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+        for (let i = 1; i <= m; i++) {
+            for (let j = 1; j <= n; j++) {
+                dp[i][j] = a[i - 1] === b[j - 1]
+                    ? dp[i - 1][j - 1]
+                    : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+            }
+        }
+        return dp[m][n];
+    }
+}
+export function createCommandHub() {
+    return new CommandHub();
+}

package/dist/config/loader.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Configuration management for Zouroboros
+ */
+import type { ZouroborosConfig } from '../types.js';
+import { DEFAULT_CONFIG, DEFAULT_CONFIG_PATH } from '../constants.js';
+export { DEFAULT_CONFIG, DEFAULT_CONFIG_PATH };
+export { validateConfigSchema, formatValidationErrors } from './schema.js';
+export type { ConfigValidationIssue } from './schema.js';
+/**
+ * Configuration validation error
+ */
+export declare class ConfigValidationError extends Error {
+    path: string;
+    constructor(message: string, path: string);
+}
+/**
+ * Load configuration from file or return defaults
+ */
+export declare function loadConfig(configPath?: string): ZouroborosConfig;
+/**
+ * Save configuration to file
+ */
+export declare function saveConfig(config: ZouroborosConfig, configPath?: string): void;
+/**
+ * Merge partial config with defaults
+ */
+export declare function mergeConfig(partial: Partial<ZouroborosConfig>): ZouroborosConfig;
+/**
+ * Validate configuration structure using Zod schemas.
+ * Throws ConfigValidationError with actionable messages on failure.
+ */
+export declare function validateConfig(config: unknown): ZouroborosConfig;
+/**
+ * Get a nested config value by path
+ */
+export declare function getConfigValue<T>(config: ZouroborosConfig, path: string): T | undefined;
+/**
+ * Set a nested config value by path
+ */
+export declare function setConfigValue<T>(config: ZouroborosConfig, path: string, value: T): ZouroborosConfig;
+/**
+ * Initialize configuration with interactive prompts
+ */
+export declare function initConfig(options?: {
+    force?: boolean;
+    workspaceRoot?: string;
+    dataDir?: string;
+}): Promise<ZouroborosConfig>;

package/dist/config/loader.js

@@ -0,0 +1,145 @@
+/**
+ * Configuration management for Zouroboros
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { DEFAULT_CONFIG, DEFAULT_CONFIG_PATH } from '../constants.js';
+import { validateConfigSchema, formatValidationErrors } from './schema.js';
+export { DEFAULT_CONFIG, DEFAULT_CONFIG_PATH };
+export { validateConfigSchema, formatValidationErrors } from './schema.js';
+/**
+ * Configuration validation error
+ */
+export class ConfigValidationError extends Error {
+    path;
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = 'ConfigValidationError';
+    }
+}
+/**
+ * Load configuration from file or return defaults
+ */
+export function loadConfig(configPath = DEFAULT_CONFIG_PATH) {
+    if (!existsSync(configPath)) {
+        return { ...DEFAULT_CONFIG };
+    }
+    try {
+        const content = readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        return mergeConfig(parsed);
+    }
+    catch (error) {
+        throw new ConfigValidationError(`Failed to parse config at ${configPath}: ${error instanceof Error ? error.message : String(error)}`, configPath);
+    }
+}
+/**
+ * Save configuration to file
+ */
+export function saveConfig(config, configPath = DEFAULT_CONFIG_PATH) {
+    const validated = validateConfig(config);
+    validated.updatedAt = new Date().toISOString();
+    const dir = dirname(configPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(configPath, JSON.stringify(validated, null, 2), 'utf-8');
+}
+/**
+ * Merge partial config with defaults
+ */
+export function mergeConfig(partial) {
+    return {
+        ...DEFAULT_CONFIG,
+        ...partial,
+        core: { ...DEFAULT_CONFIG.core, ...partial.core },
+        memory: { ...DEFAULT_CONFIG.memory, ...partial.memory },
+        swarm: {
+            ...DEFAULT_CONFIG.swarm,
+            ...partial.swarm,
+            circuitBreaker: { ...DEFAULT_CONFIG.swarm.circuitBreaker, ...partial.swarm?.circuitBreaker },
+            retryConfig: { ...DEFAULT_CONFIG.swarm.retryConfig, ...partial.swarm?.retryConfig },
+        },
+        personas: { ...DEFAULT_CONFIG.personas, ...partial.personas },
+        selfheal: {
+            ...DEFAULT_CONFIG.selfheal,
+            ...partial.selfheal,
+            metrics: { ...DEFAULT_CONFIG.selfheal.metrics, ...partial.selfheal?.metrics },
+        },
+    };
+}
+/**
+ * Validate configuration structure using Zod schemas.
+ * Throws ConfigValidationError with actionable messages on failure.
+ */
+export function validateConfig(config) {
+    if (typeof config !== 'object' || config === null) {
+        throw new ConfigValidationError('Config must be an object', '');
+    }
+    const issues = validateConfigSchema(config);
+    if (issues) {
+        throw new ConfigValidationError(formatValidationErrors(issues), issues[0]?.path ?? '');
+    }
+    return config;
+}
+/**
+ * Get a nested config value by path
+ */
+export function getConfigValue(config, path) {
+    const parts = path.split('.');
+    let current = config;
+    for (const part of parts) {
+        if (typeof current !== 'object' || current === null) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Set a nested config value by path
+ */
+export function setConfigValue(config, path, value) {
+    const parts = path.split('.');
+    const newConfig = structuredClone(config);
+    let current = newConfig;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+    newConfig.updatedAt = new Date().toISOString();
+    return validateConfig(newConfig);
+}
+/**
+ * Initialize configuration with interactive prompts
+ */
+export async function initConfig(options = {}) {
+    const configPath = DEFAULT_CONFIG_PATH;
+    if (existsSync(configPath) && !options.force) {
+        throw new Error(`Config already exists at ${configPath}. Use --force to overwrite.`);
+    }
+    const config = {
+        ...DEFAULT_CONFIG,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+    };
+    if (options.workspaceRoot) {
+        config.core.workspaceRoot = options.workspaceRoot;
+    }
+    if (options.dataDir) {
+        config.core.dataDir = options.dataDir;
+        config.memory.dbPath = join(options.dataDir, 'memory.db');
+        config.swarm.registryPath = join(options.dataDir, 'executor-registry.json');
+    }
+    // Ensure data directory exists
+    if (!existsSync(config.core.dataDir)) {
+        mkdirSync(config.core.dataDir, { recursive: true });
+    }
+    saveConfig(config, configPath);
+    return config;
+}