citadel_cli 1.0.0 → 1.1.3

package/README.md

@@ -1,257 +1,208 @@
-# Citadel
+# Citadel CLI
 
-A hierarchical command-line interface (CLI) for web applications.
+Citadel CLI enhances React applications by adding a keyboard-driven command line component to your application, allowing rapid task execution for power users and developers.
+
+## Use Cases
+
+- **API Testing & Debugging**: Execute REST calls, inspect responses, and manipulate cookies/localStorage without leaving your
+application context
+- **Power User Workflows**: Transform repetitive click-through sequences into fast keyboard commands for advanced users
+- **DevOps Integration**: Add command-line control to CI/CD dashboards and deployment tools for rapid operations
+- **Internal Tool Enhancement**: Give your team's web applications the speed and efficiency of terminal interfaces
+- Perform (multiple) REST API calls & view results, view/modify cookies/localstorage. Do JavaScript things without affecting the application.
+
+![Animated screenshot of Citadel CLI](https://github.com/user-attachments/assets/b64da0f7-a4a0-4f76-bc03-c0e40c0e14e5)
+
+# Installation
+
+```bash
+npm install citadel_cli
+```
 
 ## Quick Start
 
+In your application:
+
 ```typescript
-import { Citadel, CommandTrie } from 'citadel';
-
-// Initialize command system
-const commands = new CommandTrie();
-
-// Register commands
-commands.addCommand(
-  ['customer', 'search'],
-  'Search for customer records',
-  async (args) => ({
-    json: await customerService.search(args.query)
-  }),
-  { name: 'query', description: 'Customer name or ID' }
-);
 
-// Mount in your React app
+import { Citadel } from "citadel_cli";
+
 function App() {
   return (
-    <div>
-      <Citadel commands={commands} />
-      {/* Your app content */}
-    </div>
+    <>
+      <Citadel />
+    </>
   );
 }
 ```
 
-## Command Usage
+Press <kbd>.</kbd> (period) to activate Citadel.
 
-Citadel commands composed of one or more words followed by zero or one arguments. For example:
-```
-> ticket new customer 1234
-```
-Where the user typed "tnc1234" to achieve the above result.
+Now this doesn't do much, yet: it just shows the "help" command. You can
+execute it by pressing <kbd>h[Enter]</kbd>. If you do then you should see the
+following:
+
+![screenshot_help_cmd](https://github.com/user-attachments/assets/1cc6fd58-7591-45f1-980a-46da15a1843a)
+
+## Adding Commands
+
+To add your own commands:
 
+1. Create a `CommandRegistry` object
+2. Add commands to the registry object via the `addCommand` function
+3. Pass the registry to the `Citadel` component
 
-### Quick Execution
+For example, let's add a simple `greet` command. 
 
-Commands can be typed using abbreviated forms. For example:
 ```
-ticket new   →  tn
-deploy status  →  ds
-customer history  →  ch
+import { Citadel, CommandRegistry, TextCommandResult } from "citadel_cli";
+
+// 1. Create the registry where your commands will be stored
+const cmdRegistry = new CommandRegistry();
+
+// 2. Add a command to the registry. This can be called as many times as you like.
+cmdRegistry.addCommand(
+  [
+    { type: 'word', name: 'greet' },
+    { type: 'argument', name: 'name', description: 'Enter your name' }
+  ],
+  'Say hello to the world', // The description of this command. Used by "help".
+
+  // Next comes the "handler", which is what will get called when the user hits enter.
+  // The return type for this handler is `TextCommandResult`. There are other
+  // types of command result that we'll cover later.
+  async (args: string[]) => new TextCommandResult(`Hello, ${args[0]}!`) 
+);
 ```
+The first argument to the `addCommand` function is an array of "command
+segments". There are two types of command segments: `word`s and `argument`s.
+Here we are defining a command with two segments named `greet` and `name`.
+`greet` being a `word` segment and `name` being an `argument`. 
 
-Simply type the first letter of each word in the command and press Enter. 
+Word segments are autocompleted, whereas argument segments are used to store
+user-entered values. 
 
-### Arguments
+A few notes on arguments:
 
-Commands can have zero or more arguments.
+1. You can have zero or more arguments in a command, and they can appear in any
+   order.
+2. The arguments the user enters will be passed to the handler as an array of
+   strings.
+3. Arguments can be single- or double-quoted. This allows users to enter in
+   values that have spaces or other special characters.
 
-```bash
-> ticket new customer 1234 
-```
+Continuing on with our `greet` example, after the segments are defined is a
+description ("Say hello..."). This is the text that will be shown by the help
+command.
+
+The final argument to `addCommand` is the *handler*. Let's go over that:
 
-### JavaScript Integration
+```
+  async (args: string[]) => new TextCommandResult(`Hello, ${args[0]}!`)
+```
 
-Commands can execute any JavaScript code, making them powerful automation tools:
+As mentioned before this is what will be called after the user hits Enter. The
+values for the arguments entered by the user (if any) are passed in to the
+handler as `args: string[]`. What you do inside the handler is completely up to
+your imagination. For example, say you wanted to clear the localstorage:
 
-```typescript
-commands.addCommand(
-  ['refresh', 'cache'],
-  'Refresh application cache',
-  async () => {
-    // Clear local storage
+```
+  async (_args: string[]) => {
     localStorage.clear();
-    // Reset Redux store
-    store.dispatch(resetState());
-    // Reload application
-    window.location.reload();
-    return { json: { status: 'Cache cleared' } };
+    return new TextCommandResult('localStorage cleared!');
   }
-);
 ```
 
-### Dynamic Results
-
-Commands can return different types of results:
-- JSON data for structured information
-- React components for rich visualizations
-- Plain text for simple outputs
-- Promises for async operations
+Or perhaps make an HTTP POST and return the result as JSON:
 
-```typescript
-commands.addCommand(
-  ['user', 'activity'],
-  'Show user activity',
-  async (args) => ({
-    // Return both data and visualization
-    json: await getUserActivity(args.userId),
-    component: <ActivityGraph userId={args.userId} />
-  })
-);
+```
+async (args: string[]) => {
+  const response = await fetch('https://api.example.com/endpoint', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ name: args[0] }),
+  });
+  return new JsonCommandResult(await response.json());
+}
 ```
 
-## Real-World Examples
+At the time of this writing the following command result types are available:
 
-### Customer Service Application
+- `ErrorCommandResult`
+- `ImageCommandResult`
+- `JsonCommandResult`
+- `TextCommandResult`
 
-```typescript
-// Customer service command configuration
-commands.addCommand(
-  ['ticket', 'new'],
-  'Create support ticket',
-  async (args) => {
-    const ticket = await ticketService.create({
-      customerId: args.customer,
-      priority: args.priority,
-      description: args.description
-    });
-    return { json: { ticketId: ticket.id, status: 'created' } };
-  },
-  [
-    { name: 'customer', description: 'Customer ID' },
-    { name: 'priority', description: 'Ticket priority (high|medium|low)' },
-    { name: 'description', description: 'Issue description' }
-  ]
-);
+Back to our `greeting` command. The final code for it (without comments) should
+now look like this:
 
-commands.addCommand(
-  ['customer', 'history'],
-  'View customer interaction history',
-  async (args) => ({
-    json: await customerService.getHistory(args.id, {
-      last: args.days || 30
-    })
-  }),
-  [
-    { name: 'id', description: 'Customer ID' },
-    { name: 'days', description: 'Number of days (default: 30)' }
-  ]
-);
 ```
+import { CommandRegistry, TextCommandResult } from "citadel_cli";
 
-### Trading Platform Integration
+const cmdRegistry = new CommandRegistry();
 
-```typescript
-// Trading command configuration
-commands.addCommand(
-  ['trade', 'limit'],
-  'Place limit order',
-  async (args) => {
-    const order = await tradingService.placeLimitOrder({
-      pair: args.pair,
-      price: args.price,
-      quantity: args.quantity,
-      side: args.side || 'buy'
-    });
-    return { json: { orderId: order.id, status: order.status } };
-  },
+cmdRegistry.addCommand(
   [
-    { name: 'pair', description: 'Trading pair (e.g., btc-usd)' },
-    { name: 'price', description: 'Limit price' },
-    { name: 'quantity', description: 'Order quantity' },
-    { name: 'side', description: 'Order side (buy|sell)' }
-  ]
+    { type: 'word', name: 'greet' },
+    { type: 'argument', name: 'name', description: 'Enter your name' }
+  ],
+  'Say hello to the world',
+  async (args: string[]) => new TextCommandResult(`Hello, ${args[0]}!`) 
 );
 ```
+Now that the command has been added all that is left is to pass the registry to
+the `Citadel` component:
 
-### DevOps Dashboard Commands
-
-```typescript
-// Deployment command configuration
-commands.addCommand(
-  ['deploy', 'status'],
-  'Check deployment status',
-  async (args) => ({
-    json: await deploymentService.getStatus(args.service, args.environment)
-  }),
-  [
-    { name: 'service', description: 'Service name' },
-    { name: 'environment', description: 'Environment (dev|staging|prod)' }
-  ]
-);
-
-commands.addCommand(
-  ['metrics', 'alert'],
-  'Configure service alerts',
-  async (args) => ({
-    json: await metricsService.setAlert(args.service, {
-      metric: args.metric,
-      threshold: args.threshold,
-      duration: args.duration
-    })
-  }),
-  [
-    { name: 'service', description: 'Service name' },
-    { name: 'metric', description: 'Metric name (cpu|memory|latency)' },
-    { name: 'threshold', description: 'Alert threshold' },
-    { name: 'duration', description: 'Duration in minutes' }
-  ]
-);
+```
+<Citadel commandRegistry={cmdRegistry} />
 ```
 
-## Advanced Configuration
+The result of this should look like this:
 
-### Custom Command Rendering
+![screenshot_greeting_cmd](https://github.com/user-attachments/assets/a3c1acad-69b3-4079-87af-0425aea3980a)
 
-Citadel supports custom rendering of command results:
+Go forth and make your application experience better!
 
-```typescript
-commands.addCommand(
-  ['dashboard', 'metrics'],
-  'Show service metrics',
-  async (args) => ({
-    component: <MetricsVisualization serviceId={args.service} />,
-    json: await metricsService.get(args.service)
-  }),
-  { name: 'service', description: 'Service ID' }
-);
-```
+## Configuration
 
-### Authentication Integration
+Certain configuration options can be passed to the Citadel component. These are
+given below, along with their default values.
 
-```typescript
-const citadelConfig = {
-  commandFilter: (command) => {
-    const userPermissions = getUserPermissions();
-    return command.requiredPermissions.every(
-      (perm) => userPermissions.includes(perm)
-    );
-  },
-  // ... other config
+```
+const config = {
+  commandTimeoutMs: 10000,
+  includeHelpCommand: true,
+  maxHeight: '80vh',
+  initialHeight: '40vh',
+  minHeight: '200',
+  outputFontSize: '0.875rem',
+  resetStateOnHide: false,
+  showCitadelKey: '.',
+  cursorType: 'bbs', // 'blink', 'spin', 'solid', or 'bbs'
+  cursorSpeed: 530,
+  storage: {
+    type: 'localStorage',
+    maxCommands: 100
+  }
 };
 ```
 
-## Development
+Then to make the component aware of them:
 
-### Project Structure
 ```
-citadel/
-├── src/
-│   ├── components/    # React components
-│   ├── styles/        # CSS and theme files
-│   ├── types/         # TypeScript definitions
-│   └── utils/         # Utility functions
-├── public/            # Static assets
-└── vite.config.ts     # Vite configuration
+<Citadel commandRegistry={cmdRegistry} config={config} />
 ```
 
-### Contributing
+## Contributing
 
 Contributions are welcome.
 
 1. Clone the repository:
 ```bash
-git clone https://github.com/jchilders/citadel.git
-cd citadel
+git clone https://github.com/jchilders/citadel_cli.git
+cd citadel_cli
 ```
 
 2. Install dependencies:
@@ -271,10 +222,12 @@ npm link
 
 5. (Optional) From the directory of the project you want to import Citadel into:
 ```bash
-npm link @jchilders/citadel
-# ... your normal build/run steps ...
+npm unlink citadel_cli && npm link citadel_cli
+# ... your normal dev process ...
 ```
 
+Load your appliation and press <kbd>.</kbd>
+
 ### Bug Reports and Feature Requests
 
 - Use the GitHub Issues section to report bugs or suggest features
@@ -299,7 +252,7 @@ npm link @jchilders/citadel
 4. Write or update tests as needed
 5. Run the test suite to ensure everything passes:
    ```bash
-   npm test
+   npm run test
    ```
 6. Commit your changes with a clear and descriptive commit message
 7. Push to your fork and submit a pull request
@@ -321,17 +274,3 @@ npm link @jchilders/citadel
 - Keep functions focused and modular
 - Use consistent formatting (the project uses ESLint and Prettier)
 
-## License
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-Citadel is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
-
-This means you can use Citadel in your own projects (commercial or non-commercial) as long as you include the original copyright notice and license terms. The MIT License is simple and permissive, allowing you to:
-
-- Use the code commercially
-- Modify the code
-- Distribute the code
-- Use in private/closed-source projects
-
-All we ask is that you include the original license and copyright notice in any copy or substantial portion of the software.

package/dist/App.d.ts

@@ -0,0 +1,2 @@
+declare function App(): import("react/jsx-runtime").JSX.Element;
+export default App;

package/dist/__test-utils__/factories.d.ts

@@ -0,0 +1,40 @@
+import { CommandNode, CommandRegistry, CommandHandler, CommandSegment } from '../components/Citadel/types/command-registry';
+import { CitadelState, CitadelActions, OutputItem } from '../components/Citadel/types';
+import { SegmentStack } from '../components/Citadel/types/segment-stack';
+import { CommandHistory, CommandHistoryActions } from '../components/Citadel/hooks/useCommandHistory';
+import { StoredCommand } from '../components/Citadel/types/storage';
+interface MockNodeOptions {
+    handler?: CommandHandler;
+    description?: string;
+}
+export declare const createMockSegment: (type: "word" | "argument" | "null", name?: string, description?: string) => CommandSegment;
+export declare const createMockCommandSegment: (type: "word" | "argument", name: string, description?: string) => CommandSegment;
+export declare const createMockCommand: (name: string, options?: MockNodeOptions) => CommandNode;
+export declare const createMockCommandRegistry: () => CommandRegistry;
+export declare const createMockStoredCommand: (overrides?: {}) => StoredCommand;
+export declare const createMockStorage: () => {
+    addStoredCommand: import('vitest').Mock<(...args: any[]) => any>;
+    getStoredCommands: import('vitest').Mock<(...args: any[]) => any>;
+    clear: import('vitest').Mock<(...args: any[]) => any>;
+};
+export declare const createMockCommandHistory: (overrides?: {}) => CommandHistory;
+export declare const createMockCommandHistoryActions: (overrides?: {}) => CommandHistoryActions;
+export declare const createMockCitadelState: (overrides?: {}) => CitadelState;
+export declare const createMockOutputItem: (command?: string[]) => OutputItem;
+export declare const setupCitadelStateHook: () => {
+    hook: import('@testing-library/react').RenderHookResult<{
+        state: CitadelState;
+        actions: CitadelActions;
+        getAvailableCommands_s: () => string[];
+        getAvailableCommandSegments: () => CommandSegment[];
+    }, unknown>;
+    mockHistory: CommandHistory;
+    mockActions: CommandHistoryActions;
+    mockCommands: CommandRegistry;
+    mockStack: SegmentStack;
+};
+export declare const createMockCitadelActions: (overrides?: {}) => CitadelActions;
+export declare const createMockSegmentStack: () => SegmentStack;
+export declare const createMockKeyboardEvent: (key: string) => KeyboardEvent;
+export declare const createTestCommand: (path: string[], description?: string, handler?: CommandHandler) => CommandNode;
+export {};

package/dist/citadel.css

@@ -1 +1 @@
-._container_141sr_3{position:fixed;height:var(--citadel-default-height);min-height:var(--citadel-min-height);max-height:var(--citadel-max-height);background-color:var(--citadel-bg);overflow:hidden;width:100%;box-sizing:border-box;margin:0;padding:0;bottom:0;left:0;right:0}._innerContainer_141sr_19{height:100%;width:100%;display:flex;flex-direction:column;margin:0;padding:0}._inputSection_141sr_28{border-top:1px solid var(--citadel-border);padding:1rem;margin:0;box-sizing:border-box}._resizeHandle_141sr_35{width:100%;height:6px;background:transparent;cursor:ns-resize;position:absolute;top:-3px;left:0;right:0;z-index:10;-moz-user-select:none;user-select:none;-webkit-user-select:none;pointer-events:all}._resizeHandle_141sr_35:hover{background:#ffffff1a}@keyframes _citadel_slideUp_141sr_64{0%{transform:translateY(100%)}to{transform:translateY(0)}}@keyframes _citadel_slideDown_141sr_68{0%{transform:translateY(0)}to{transform:translateY(100%)}}._citadel_slideUp_141sr_64{animation:_citadel_slideUp_141sr_64 .2s ease-out forwards}._citadel_slideDown_141sr_68{animation:_citadel_slideDown_141sr_68 .2s ease-out forwards}@keyframes _shake_e9b9w_1{0%,to{transform:translate(0)}25%{transform:translate(-4px)}75%{transform:translate(4px)}}@keyframes _flashBorder_e9b9w_1{0%,to{border-color:transparent}50%{border-color:#ef4444}}._invalidInput_e9b9w_12{animation:_shake_e9b9w_1 .2s ease-in-out,_flashBorder_e9b9w_1 .3s ease-in-out;border-width:1px;border-style:solid}
+._container_141sr_3{position:fixed;height:var(--citadel-default-height);min-height:var(--citadel-min-height);max-height:var(--citadel-max-height);background-color:var(--citadel-bg);overflow:hidden;width:100%;box-sizing:border-box;margin:0;padding:0;bottom:0;left:0;right:0}._innerContainer_141sr_19{height:100%;width:100%;display:flex;flex-direction:column;margin:0;padding:0}._inputSection_141sr_28{border-top:1px solid var(--citadel-border);padding:1rem;margin:0;box-sizing:border-box}._resizeHandle_141sr_35{width:100%;height:6px;background:transparent;cursor:ns-resize;position:absolute;top:-3px;left:0;right:0;z-index:10;-moz-user-select:none;user-select:none;-webkit-user-select:none;pointer-events:all}._resizeHandle_141sr_35:hover{background:#ffffff1a}@keyframes _citadel_slideUp_141sr_64{0%{transform:translateY(100%)}to{transform:translateY(0)}}@keyframes _citadel_slideDown_141sr_68{0%{transform:translateY(0)}to{transform:translateY(100%)}}._citadel_slideUp_141sr_64{animation:_citadel_slideUp_141sr_64 .2s ease-out forwards}._citadel_slideDown_141sr_68{animation:_citadel_slideDown_141sr_68 .2s ease-out forwards}