citadel_cli 1.0.0 → 1.1.0

package/dist/src/components/Citadel/config/types.d.ts

@@ -1,26 +1,42 @@
 import { CursorType } from '../types/cursor';
 import { StorageConfig } from '../types/storage';
+import { LogLevel } from '../utils/logger';
 export interface CitadelConfig {
     /**
-     * Configuration for command history storage
+     * The time in milliseconds before a command execution fails with a timeout.
      */
-    storage?: StorageConfig;
+    commandTimeoutMs?: number;
     /**
-     * Whether to include the default help command in the command trie.
+     * The color of the cursor.
+     * Accepts any valid CSS color value.
      */
-    includeHelpCommand?: boolean;
+    cursorColor?: string;
     /**
-     * Whether to reset the state when the interface is hidden (via Escape key or other means).
+     * The speed of the cursor animation in milliseconds.
+     * - For 'blink': Time between blinks (default: 530ms)
+     * - For 'spin' and 'bbs': Time between frame changes (default: 120ms)
+     * - For 'solid': Has no effect
      */
-    resetStateOnHide?: boolean;
+    cursorSpeed?: number;
     /**
-     * The keyboard key that shows the command interface.
+     * The type of cursor to display. Can be one of 'blink', 'spin', 'solid', or 'bbs'.
      */
-    showCitadelKey?: string;
+    cursorType?: CursorType;
     /**
-     * The time in milliseconds before a command execution fails with a timeout.
+     * Whether to include the default help command in the command regsitry.
      */
-    commandTimeoutMs?: number;
+    includeHelpCommand?: boolean;
+    /**
+     * The initial height of the command interface.
+     * Accepts any valid CSS height value.
+     * Example: '400px' or '50vh'
+     */
+    initialHeight?: string;
+    /**
+     * The log level for Citadel's logger
+     * @default LogLevel.DEBUG in development, LogLevel.ERROR in production
+     */
+    logLevel?: LogLevel;
     /**
      * Optional CSS value for the maximum height of the command interface.
      * If provided, this value will be set as the `max-height` property of the interface.
@@ -38,19 +54,15 @@ export interface CitadelConfig {
      */
     outputFontSize?: string;
     /**
-     * The type of cursor to display. Can be one of 'blink', 'spin', 'solid', or 'bbs'.
+     * Whether to reset the state when the interface is hidden (via Escape key or other means).
      */
-    cursorType?: CursorType;
+    resetStateOnHide?: boolean;
     /**
-     * The color of the cursor.
-     * Accepts any valid CSS color value.
+     * The keyboard key that shows the command interface.
      */
-    cursorColor?: string;
+    showCitadelKey?: string;
     /**
-     * The speed of the cursor animation in milliseconds.
-     * - For 'blink': Time between blinks (default: 530ms)
-     * - For 'spin' and 'bbs': Time between frame changes (default: 120ms)
-     * - For 'solid': Has no effect
+     * Configuration for command history storage
      */
-    cursorSpeed?: number;
+    storage?: StorageConfig;
 }

package/dist/src/components/Citadel/hooks/useCitadelState.d.ts

@@ -2,5 +2,6 @@ import { CitadelState, CitadelActions } from '../types/state';
 export declare const useCitadelState: () => {
     state: CitadelState;
     actions: CitadelActions;
-    getAvailableCommands: () => import('../types/command-trie').CommandNode[];
+    getAvailableCommands_s: () => string[];
+    getAvailableCommandSegments: () => import('../types/command-registry').CommandSegment[];
 };

package/dist/src/components/Citadel/hooks/useCommandHistory.d.ts

@@ -1,17 +1,27 @@
 import { StoredCommand } from '../types/storage';
+import { CommandSegment } from '../types/command-registry';
 export interface CommandHistory {
-    commands: StoredCommand[];
+    storedCommands: StoredCommand[];
     position: number | null;
-    savedInput: string | null;
 }
 export interface CommandHistoryActions {
-    addCommand: (command: StoredCommand) => Promise<void>;
-    getCommands: () => StoredCommand[];
-    navigateHistory: (direction: 'up' | 'down', currentInput: string) => {
-        command: StoredCommand | null;
+    addStoredCommand: (segments: CommandSegment[]) => Promise<void>;
+    getStoredCommands: () => Promise<StoredCommand[]>;
+    navigateHistory: (direction: 'up' | 'down', currentSegments: CommandSegment[]) => Promise<{
+        segments: CommandSegment[] | null;
         position: number | null;
-    };
-    saveInput: (input: string) => void;
+    }>;
     clear: () => Promise<void>;
 }
-export declare function useCommandHistory(): [CommandHistory, CommandHistoryActions];
+export declare function createStoredCommand(segments: CommandSegment[]): StoredCommand;
+export interface CommandHistoryHook {
+    history: CommandHistory;
+    addStoredCommand: (segments: CommandSegment[]) => Promise<void>;
+    getStoredCommands: () => Promise<StoredCommand[]>;
+    navigateHistory: (direction: 'up' | 'down', currentSegments: CommandSegment[]) => Promise<{
+        segments: CommandSegment[] | null;
+        position: number | null;
+    }>;
+    clear: () => Promise<void>;
+}
+export declare function useCommandHistory(): CommandHistoryHook;

package/dist/src/components/Citadel/hooks/useCommandParser.d.ts

@@ -1,19 +1,22 @@
-import { CommandNode, CommandTrie } from '../types/command-trie';
+import { CommandNode, CommandSegment } from '../types/command-registry';
 import { CitadelState, CitadelActions } from '../types/state';
-import { StoredCommand } from '../types/storage';
-type InputState = 'idle' | 'entering_command' | 'entering_argument';
-interface UseCommandParserProps {
-    commandTrie?: CommandTrie;
-}
-export declare function useCommandParser({ commandTrie: propsTrie }?: UseCommandParserProps): {
-    handleInputChange: (newValue: string, state: CitadelState, actions: CitadelActions) => void;
-    handleKeyDown: (e: KeyboardEvent, state: CitadelState, actions: CitadelActions) => void;
-    executeCommand: (commandStack: string[], actions: CitadelActions, args?: string[]) => void;
+export type InputState = 'idle' | 'entering_command' | 'entering_argument';
+export declare const useCommandParser: () => {
+    handleInputChange: (newValue: string, actions: CitadelActions) => void;
+    handleKeyDown: (e: KeyboardEvent | React.KeyboardEvent, state: CitadelState, actions: CitadelActions) => Promise<void>;
     inputState: InputState;
-    replayCommand: (command: StoredCommand, state: CitadelState, actions: CitadelActions) => Promise<void>;
+    setInputStateWithLogging: (newState: InputState) => void;
     findMatchingCommands: (input: string, availableNodes: CommandNode[]) => CommandNode[];
-    getAutocompleteSuggestion: (input: string, availableNodes: CommandNode[]) => string | null;
-    getAvailableNodes: (currentNode?: CommandNode) => CommandNode[];
-    isValidCommandInput: (input: string, availableNodes: CommandNode[]) => boolean;
+    getAutocompleteSuggestion: (input: string) => CommandSegment;
+    getAvailableNodes: () => CommandNode[];
+    getNextExpectedSegment: () => CommandSegment;
+    isValidCommandInput: (input: string) => boolean;
 };
-export {};
+export interface ParsedInput {
+    words: string[];
+    currentWord: string;
+    isQuoted: boolean;
+    quoteChar?: "'" | '"';
+    isComplete: boolean;
+}
+export declare function parseInput(input: string): ParsedInput;

package/dist/src/components/Citadel/hooks/useSegmentStack.d.ts

@@ -0,0 +1,14 @@
+import { ArgumentSegment, CommandSegment } from '../types/command-registry';
+export interface SegmentStackActions {
+    push: (segment: CommandSegment) => void;
+    pop: () => CommandSegment;
+    peek: () => CommandSegment;
+    clear: () => void;
+    hasArguments: () => boolean;
+    getArguments: () => ArgumentSegment[];
+    path: () => string[];
+    segments: () => CommandSegment[];
+    isEmpty: () => boolean;
+    size: () => number;
+}
+export declare function useSegmentStack(): SegmentStackActions;

package/dist/src/components/Citadel/hooks/useSegmentStackVersion.d.ts

@@ -0,0 +1 @@
+export declare const useSegmentStackVersion: () => number;

package/dist/src/components/Citadel/storage/BaseStorage.d.ts

@@ -8,11 +8,11 @@ export declare abstract class BaseStorage implements CommandStorage {
     /**
      * Add a command to history, enforcing storage limits
      */
-    addCommand(command: StoredCommand): Promise<void>;
+    addStoredCommand(command: StoredCommand): Promise<void>;
     /**
      * Get all stored commands, ordered by timestamp ascending
      */
-    abstract getCommands(): Promise<StoredCommand[]>;
+    abstract getStoredCommands(): Promise<StoredCommand[]>;
     /**
      * Clear all stored commands
      */

package/dist/src/components/Citadel/storage/LocalStorage.d.ts

@@ -6,7 +6,7 @@ import { BaseStorage } from './BaseStorage';
 export declare class LocalStorage extends BaseStorage {
     private readonly storageKey;
     constructor(config: StorageConfig);
-    getCommands(): Promise<StoredCommand[]>;
+    getStoredCommands(): Promise<StoredCommand[]>;
     clear(): Promise<void>;
     protected saveCommands(commands: StoredCommand[]): Promise<void>;
 }

package/dist/src/components/Citadel/storage/MemoryStorage.d.ts

@@ -4,9 +4,9 @@ import { BaseStorage } from './BaseStorage';
  * In-memory command history storage
  */
 export declare class MemoryStorage extends BaseStorage {
-    private commands;
+    private storedCommands;
     constructor(config?: StorageConfig);
-    getCommands(): Promise<StoredCommand[]>;
+    getStoredCommands(): Promise<StoredCommand[]>;
     clear(): Promise<void>;
     protected saveCommands(commands: StoredCommand[]): Promise<void>;
 }

package/dist/src/components/Citadel/types/__tests__/command-registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/components/Citadel/types/__tests__/segment-stack.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/components/Citadel/types/command-registry.d.ts

@@ -0,0 +1,84 @@
+import { CommandResult } from './command-results';
+/** Function type for handling command execution */
+export type CommandHandler = (args: string[]) => Promise<CommandResult>;
+/**
+ * A no-op handler that returns an empty string. Used as the default handler
+ * for CommandNodes that don't specify a handler.
+ */
+export declare const NoopHandler: CommandHandler;
+/** Base interface for command segments */
+export declare abstract class BaseSegment {
+    readonly type: 'word' | 'argument' | 'null';
+    readonly name: string;
+    readonly description?: string | undefined;
+    constructor(type: 'word' | 'argument' | 'null', name: string, description?: string | undefined);
+    toString(): string;
+}
+/** Represents a null segment for empty stack operations */
+export declare class NullSegment extends BaseSegment {
+    constructor();
+}
+/** Represents a segment in a command path - either a word or argument */
+export type CommandSegment = WordSegment | ArgumentSegment | NullSegment;
+/** Represents a literal word in a command path */
+export declare class WordSegment extends BaseSegment {
+    constructor(name: string, description?: string);
+}
+/** Represents an argument that can be passed to a command, and its value*/
+export declare class ArgumentSegment extends BaseSegment {
+    value?: string | undefined;
+    readonly valid?: (() => boolean) | undefined;
+    constructor(name: string, description?: string, value?: string | undefined, valid?: (() => boolean) | undefined);
+}
+/** Defines a complete command with its path and behavior */
+export declare class CommandNode {
+    private readonly _segments;
+    private readonly _description?;
+    private readonly _handler;
+    constructor(segments: CommandSegment[], description?: string, handler?: CommandHandler);
+    get segments(): CommandSegment[];
+    get description(): string | undefined;
+    get handler(): CommandHandler;
+    get hasArguments(): boolean;
+    get fullPath(): string[];
+    get fullPath_s(): string;
+    equals(other: CommandNode): boolean;
+}
+/**
+ * Used to store user-defined commands.
+ */
+export declare class CommandRegistry {
+    private _commands;
+    get commands(): CommandNode[];
+    /**
+     * Registers a new command
+     *
+     * @param newCommandNode The new command to add
+     * @throws {Error} If attempting to add a duplicate leaf command or a subcommand to a leaf
+     *
+     */
+    addCommand(segments: CommandSegment[], description: string, handler?: CommandHandler): void;
+    /**
+     * Retrieves a command from the registry for the given path.
+     *
+     * @param path The path of the command.
+     * @returns The command node or undefined if not found.
+     */
+    getCommand(path: string[]): CommandNode | undefined;
+    commandExistsForPath(path: string[]): boolean;
+    /**
+     * Gets possible matches for a given path.
+     *
+     * @param path The path to get completions for.
+     * @returns An array of completion strings.
+     */
+    getCompletions_s(path: string[]): string[];
+    /**
+     * Gets an array of segments reachable from a given path
+     *
+     * @param path The path to get completions for.
+     * @returns An array of completion strings.
+     */
+    getCompletions(path: string[]): CommandSegment[];
+    hasNextSegment(path: string[]): boolean;
+}

package/dist/src/components/Citadel/types/command-trie.d.ts

@@ -1,146 +1,63 @@
 import { CommandResult } from './command-results';
 /** Function type for handling command execution */
 export type CommandHandler = (args: string[]) => Promise<CommandResult>;
-/**
- * Represents an argument that can be passed to a command
- */
-export interface CommandArgument {
-    name: string;
-    description: string;
-}
-export interface CommandNodeParams {
-    fullPath: string[];
-    description: string;
-    parent?: CommandNode;
-    argument?: CommandArgument;
-    handler?: CommandHandler;
-}
-export interface CommandSignature {
-    signature: string[];
-}
 /**
  * A no-op handler that returns an empty string. Used as the default handler
  * for CommandNodes that don't specify a handler.
  */
 export declare const NoopHandler: CommandHandler;
+/** Base interface for command segments */
+export declare abstract class BaseSegment {
+    readonly type: 'word' | 'argument' | 'null';
+    readonly name: string;
+    readonly description?: string | undefined;
+    constructor(type: 'word' | 'argument' | 'null', name: string, description?: string | undefined);
+    toString(): string;
+}
+/** Represents a null segment for empty stack operations */
+export declare class NullSegment extends BaseSegment {
+    constructor();
+}
+/** Represents a segment in a command path - either a word or argument */
+export type CommandSegment = WordSegment | ArgumentSegment | NullSegment;
+/** Represents a literal word in a command path */
+export declare class WordSegment extends BaseSegment {
+    constructor(name: string, description?: string);
+}
+/** Represents an argument that can be passed to a command, and its value*/
+export declare class ArgumentSegment extends BaseSegment {
+    value?: string | undefined;
+    readonly valid?: (() => boolean) | undefined;
+    constructor(name: string, description?: string, value?: string | undefined, valid?: (() => boolean) | undefined);
+}
+/** Defines a complete command with its path and behavior */
 export declare class CommandNode {
-    private _fullPath;
-    private _description;
-    private _children;
-    private _argument?;
-    private _handler;
-    private _parent?;
-    private _signature?;
-    /**
-     * Creates a new CommandNode representing a command the user can enter. From a
-     * high level, a command is one or more words followed by an optional
-     * argument, and with an optional handler.
-     *
-     * @param params Configuration parameters for the node
-     * @param params.fullPath Complete path from root to this node (e.g., ['service', 'deploy'])
-     * @param params.description Human-readable description of the command
-     * @param params.parent Optional parent node in the command hierarchy
-     * @param params.handler Optional async function to execute when command is invoked
-     * @param params.argument Optional argument definition for the command
-     * @throws {Error} If fullPath is empty or undefined
-     *
-     */
-    constructor(params: CommandNodeParams);
-    /**
-     * Gets the name of this command (last segment of the path)
-     */
-    get name(): string;
-    /**
-     * Whether this is a leaf node (has no children)
-     */
-    get isLeaf(): boolean;
-    /**
-     * Whether this command has a handler
-     */
-    get hasHandler(): boolean;
-    /**
-     * Whether this command requires an argument
-     */
-    get requiresArgument(): boolean;
-    /**
-     * Gets the parent node if it exists
-     */
-    get parent(): CommandNode | undefined;
-    /**
-     * Gets the command's signature
-     */
-    get signature(): string | undefined;
-    /**
-     * Sets the signature for this command based on the current command trie state
-     * @param trie The command trie to use for signature generation
-     */
-    setSignature(trie: CommandTrie): void;
-    /**
-     * Gets the map of child commands
-     */
-    get children(): ReadonlyMap<string, CommandNode>;
-    /**
-     * Whether this command has any children
-     */
-    get hasChildren(): boolean;
-    /**
-     * Adds a child command
-     */
-    addChild(segment: string, node: CommandNode): void;
-    /**
-     * Gets a child command by name
-     */
-    getChild(name: string): CommandNode | undefined;
-    /**
-     * Gets the full path from root to this command
-     */
-    get fullPath(): string[];
-    /**
-     * Gets the command's description
-     */
-    get description(): string;
-    /**
-     * Gets the command's argument definition if it exists
-     */
-    get argument(): CommandArgument | undefined;
-    /**
-     * Sets the command's argument definition
-     */
-    set argument(value: CommandArgument | undefined);
-    /**
-     * Gets the command's handler
-     */
+    private readonly _segments;
+    private readonly _description?;
+    private readonly _handler;
+    constructor(segments: CommandSegment[], description?: string, handler?: CommandHandler);
+    get segments(): CommandSegment[];
+    get description(): string | undefined;
     get handler(): CommandHandler;
-    /**
-     * Sets the command's handler
-     */
-    set handler(value: CommandHandler);
+    get hasArguments(): boolean;
+    get fullPath(): string[];
+    get fullPath_s(): string;
+    equals(other: CommandNode): boolean;
 }
 /**
- * A trie data structure for managing hierarchical commands.
- * Provides functionality for adding commands, retrieving commands,
- * and getting command completions.
+ * Used to store user-defined commands.
  */
-export declare class CommandTrie {
-    private readonly _root;
-    /**
-     * Creates a new CommandTrie instance.
-     */
-    constructor();
+export declare class CommandRegistry {
+    private _commands;
+    get commands(): CommandNode[];
     /**
      * Adds a new command to the trie.
      *
-     * @param params Parameters for the command.
-     * @param params.path The path segments for the command (e.g., ['service', 'deploy'])
-     * @param params.description Description of what the command does
-     * @param params.handler Optional function to execute when command is invoked
-     * @param params.argument Optional argument definition for the command
+     * @param newCommandNode The new command to add
      * @throws {Error} If attempting to add a duplicate leaf command or a subcommand to a leaf
      *
      */
-    addCommand(params: Omit<ConstructorParameters<typeof CommandNode>[0], 'fullPath' | 'parent'> & {
-        path: string[];
-    }): void;
+    addCommand(segments: CommandSegment[], description: string, handler?: CommandHandler): void;
     /**
      * Retrieves a command from the trie.
      *
@@ -148,91 +65,20 @@ export declare class CommandTrie {
      * @returns The command node or undefined if not found.
      */
     getCommand(path: string[]): CommandNode | undefined;
+    commandExistsForPath(path: string[]): boolean;
     /**
-     * Gets command completions for a given path.
+     * Gets possible matches for a given path.
      *
      * @param path The path to get completions for.
      * @returns An array of completion strings.
      */
-    getCompletions(path: string[]): string[];
+    getCompletions_s(path: string[]): string[];
     /**
-     * Executes a command with the given path and arguments.
-     * @param path The command path
-     * @param args Arguments to pass to the command handler
-     * @returns The command result or undefined if command not found
-     * @throws Error if command validation fails
-     */
-    executeCommand(path: string[], args?: string[]): Promise<CommandResult | undefined>;
-    /**
-     * Gets the root commands in the trie.
+     * Gets an array of segments reachable from a given path
      *
-     * @returns An array of root command nodes.
-     */
-    getRootCommands(): CommandNode[];
-    /**
-     * Gets the leaf commands in the trie.
-     *
-     * @returns An array of leaf command nodes.
-     */
-    getLeafCommands(): CommandNode[];
-    /**
-     * Retrieves a command using its unique signature.
-     * A signature is the minimal sequence of prefixes that uniquely identifies a command.
-     *
-     * @param signature Array of minimal prefixes that uniquely identify the command
-     * @returns The matching command node or undefined if not found
-     *
-     * @example
-     * // Will match 'image random cat' command
-     * getCommandBySignature(['i', 'r', 'c'])
-     * // Will match 'user show' command (not ambiguous with 'user status')
-     * getCommandBySignature(['u', 'sh'])
-     */
-    getCommandBySignature(signature: CommandSignature): CommandNode | undefined;
-    /**
-     * Generates a minimal unique signature for a command node.
-     * The signature consists of the shortest prefixes that uniquely identify each segment
-     * in the path from root to this node.
-     *
-     * @param command The command node to generate a signature for
-     * @returns Array of minimal prefixes that uniquely identify the command
-     *
-     * @example
-     * // For commands: ['image', 'random', 'cat'] and ['image', 'random', 'dog']
-     * buildSignatureForCommand(catCommand) // returns ['i', 'r', 'c']
-     * // For commands: ['user', 'show'] and ['user', 'status']
-     * buildSignatureForCommand(showCommand) // returns ['u', 'sh']
-     */
-    buildSignatureForCommand(command: CommandNode): CommandSignature;
-    /**
-     * Validates the command trie structure for common errors.
-     *
-     * Performs the following validations:
-     * 1. Checks for duplicate command paths
-     * 2. Ensures non-leaf nodes (nodes with children) use NoopHandler
-     * 3. Ensures non-leaf nodes don't have arguments
-     * 4. Verifies all nodes have a handler (either custom or NoopHandler)
-     * 5. Validates command path uniqueness
-     *
-     * @returns An object containing:
-     *  - isValid: boolean indicating if the trie is valid
-     *  - errors: array of error messages describing any validation failures
-     *
-     * @example
-     * ```typescript
-     * const result = commandTrie.validate();
-     * if (!result.isValid) {
-     *   console.error('Command trie validation failed:');
-     *   result.errors.forEach(error => console.error(error));
-     * }
-     * ```
-     */
-    /**
-     * Updates signatures for all nodes in the trie
+     * @param path The path to get completions for.
+     * @returns An array of completion strings.
      */
-    setSignatures(): void;
-    validate(): {
-        isValid: boolean;
-        errors: string[];
-    };
+    getCompletions(path: string[]): CommandSegment[];
+    hasNextSegment(path: string[]): boolean;
 }

package/dist/src/components/Citadel/types/help-command.d.ts

@@ -1,3 +1,3 @@
-import { CommandNode, CommandTrie } from './command-trie';
-import { CitadelConfig } from '../config/types';
-export declare const createHelpCommand: (trie: CommandTrie, config: CitadelConfig) => [string, CommandNode];
+import { CommandRegistry } from './command-registry';
+import { TextCommandResult } from './command-results';
+export declare const createHelpHandler: (cmdRegistry: CommandRegistry) => (_args: string[]) => Promise<TextCommandResult>;