citadel_cli 1.0.0

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

@@ -0,0 +1,238 @@
+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;
+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
+     */
+    get handler(): CommandHandler;
+    /**
+     * Sets the command's handler
+     */
+    set handler(value: CommandHandler);
+}
+/**
+ * A trie data structure for managing hierarchical commands.
+ * Provides functionality for adding commands, retrieving commands,
+ * and getting command completions.
+ */
+export declare class CommandTrie {
+    private readonly _root;
+    /**
+     * Creates a new CommandTrie instance.
+     */
+    constructor();
+    /**
+     * 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
+     * @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;
+    /**
+     * Retrieves a command from the trie.
+     *
+     * @param path The path of the command.
+     * @returns The command node or undefined if not found.
+     */
+    getCommand(path: string[]): CommandNode | undefined;
+    /**
+     * Gets command completions for a given path.
+     *
+     * @param path The path to get completions for.
+     * @returns An array of completion strings.
+     */
+    getCompletions(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.
+     *
+     * @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
+     */
+    setSignatures(): void;
+    validate(): {
+        isValid: boolean;
+        errors: string[];
+    };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Defines the available cursor animation types.
+ * - 'blink': Traditional blinking cursor
+ * - 'spin': Spinning animation cursor
+ * - 'solid': Static cursor
+ * - 'bbs': BBS-style cursor
+ */
+export type CursorType = 'blink' | 'spin' | 'solid' | 'bbs';
+/**
+ * Configuration interface for cursor appearance and behavior
+ */
+export interface CursorStyle {
+    /** The type of cursor animation */
+    type: CursorType;
+    /** The character to display as the cursor */
+    character?: string;
+    /** Animation speed in milliseconds */
+    speed?: number;
+    /** CSS color value for the cursor */
+    color?: string;
+}
+/**
+ * Default configurations for each cursor type
+ * Provides complete configurations with all optional properties defined
+ */
+export declare const DEFAULT_CURSOR_CONFIGS: Record<CursorType, Required<Omit<CursorStyle, 'type'>>>;

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

@@ -0,0 +1,3 @@
+import { CommandNode, CommandTrie } from './command-trie';
+import { CitadelConfig } from '../config/types';
+export declare const createHelpCommand: (trie: CommandTrie, config: CitadelConfig) => [string, CommandNode];

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

@@ -0,0 +1,3 @@
+export * from './state';
+export * from './cursor';
+export * from './command-results';

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

@@ -0,0 +1,40 @@
+import { CommandNode } from './command-trie';
+import { CommandResult } from './command-results';
+import { CommandStorage, StoredCommand } from './storage';
+export declare class OutputItem {
+    readonly timestamp: number;
+    readonly command: string[];
+    result: CommandResult;
+    constructor(command: string[], result?: CommandResult);
+}
+export interface CitadelState {
+    commandStack: string[];
+    currentInput: string;
+    isEnteringArg: boolean;
+    currentNode?: CommandNode;
+    output: OutputItem[];
+    validation: {
+        isValid: boolean;
+        message?: string;
+    };
+    history: {
+        commands: StoredCommand[];
+        position: number | null;
+        savedInput: string | null;
+        storage?: CommandStorage;
+    };
+}
+export interface CitadelActions {
+    setCommandStack: (stack: string[]) => void;
+    setCurrentInput: (input: string) => void;
+    setIsEnteringArg: (isEntering: boolean) => void;
+    setCurrentNode: (node: CommandNode | undefined) => void;
+    addOutput: (output: OutputItem) => void;
+    setValidation: (validation: {
+        isValid: boolean;
+        message?: string;
+    }) => void;
+    executeCommand: (path: string[], args?: string[]) => Promise<void>;
+    executeHistoryCommand: (index: number) => Promise<void>;
+    clearHistory: () => Promise<void>;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Supported storage mechanisms for command history
+ */
+export type StorageType = 'localStorage' | 'memory';
+/**
+ * Configuration options for command history storage
+ */
+export interface StorageConfig {
+    /**
+     * The storage mechanism to use for command history.
+     * Defaults to 'localStorage' with fallback to 'memory' if unavailable.
+     */
+    type?: StorageType;
+    /**
+     * Maximum number of commands to store in history.
+     * When exceeded, oldest commands will be removed.
+     * Default is 100.
+     */
+    maxCommands?: number;
+}
+/**
+ * Represents a command entry to be stored in history
+ */
+export interface StoredCommand {
+    inputs: string[];
+    timestamp: number;
+}
+/**
+ * Interface for command history storage implementations
+ */
+export interface CommandStorage {
+    /**
+     * Add a command to storage
+     */
+    addCommand: (command: StoredCommand) => Promise<void>;
+    /**
+     * Get all stored commands
+     */
+    getCommands: () => Promise<StoredCommand[]>;
+    /**
+     * Clear all stored commands
+     */
+    clear: () => Promise<void>;
+}

package/dist/src/components/Citadel/utils/keySimulation.d.ts

@@ -0,0 +1,2 @@
+import { CitadelState, CitadelActions } from '../types/state';
+export declare const simulateKeyPress: (key: string, state: CitadelState, actions: CitadelActions) => void;

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export { Citadel } from './components/Citadel/Citadel';
+export type { CitadelProps } from './components/Citadel/Citadel';
+export type { CitadelConfig } from './components/Citadel/config/types';
+export * from './components/Citadel/types';

package/dist/src/main.d.ts

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

package/dist/src/test/setup.d.ts

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

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "citadel_cli",
+  "description": "A hierarchical command line and console for your webapp",
+  "keywords": [
+    "react",
+    "command",
+    "cli",
+    "interface",
+    "console"
+  ],
+  "author": "James Childers <james.childers@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jchilders/citadel_react.git"
+  },
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc && vite build",
+    "dev": "vite",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "test": "vitest --run",
+    "coverage": "vitest run --coverage"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "style": "./dist/citadel.css",
+      "import": "./dist/citadel.es.js",
+      "require": "./dist/citadel.umd.cjs"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./citadel.css": "./dist/citadel.css"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/citadel.umd.cjs",
+  "module": "./dist/citadel.es.js",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "lucide-react": "^0.460.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.13.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/react": "^18.2.64",
+    "@types/react-dom": "^18.2.21",
+    "@vitejs/plugin-react": "^4.3.3",
+    "@vitest/coverage-v8": "^2.1.6",
+    "autoprefixer": "^10.4.20",
+    "eslint": "^9.13.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.14",
+    "globals": "^15.11.0",
+    "jsdom": "^25.0.1",
+    "playwright": "^1.49.0",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.4.2",
+    "typescript-eslint": "^8.11.0",
+    "vite": "^5.1.5",
+    "vite-plugin-dts": "^4.5.0",
+    "vitest": "^2.1.6",
+    "webpack-cli": "^6.0.1"
+  }
+}