citadel_cli 1.0.0 → 1.1.0

package/README.md

@@ -1,257 +1,210 @@
-# Citadel
+# Citadel CLI
 
 A hierarchical command-line interface (CLI) for web applications.
 
+Use cases:
+
+- Developers: Perform (multiple) REST API calls & view results, view/modify
+  cookies/localstorage. Do JavaScript things without affecting the application.
+- "Poor man's Postman": execute API calls within the context of your application
+- Devops: Improve how you interface with your existing CI/CD web app
+- Power users: Provide a hook for advanced users of your internal or external
+  applications to quickly perform complex actions
+
+![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)
+
+When you execute a command the result is displayed in the output area. It shows
+the command that was executed, a timestamp, whether the command succesfully
+executed, and the command's output.
+
+Adding your own commands is pretty straightforward. There are three steps to doing so.
 
+1. Create a `CommandRegistry`
+2. Add commands to the registry
+3. Pass the registry to the `Citadel` component
 
-### Quick Execution
+Let's add a simple `greet` command to demonstrate this. 
 
-Commands can be typed using abbreviated forms. For example:
 ```
-ticket new   →  tn
-deploy status  →  ds
-customer history  →  ch
+import { 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 +224,12 @@ npm link
 
 5. (Optional) From the directory of the project you want to import Citadel into:
 ```bash
-npm link @jchilders/citadel
+npm link @jchilders/citadel_cli
 # ... your normal build/run steps ...
 ```
 
+Load your appliation and press <kbd>.</kbd>
+
 ### Bug Reports and Feature Requests
 
 - Use the GitHub Issues section to report bugs or suggest features
@@ -321,17 +276,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.