citadel_cli 1.1.6 → 1.3.0

package/README.md

@@ -24,31 +24,27 @@ npm i citadel_cli
 A core concept in Citadel are commands. Commands are things like "user add 1234"
 or "qa1 deploy my_feature_branch". To initialize and add commands:
 
-1. Create a `CommandRegistry` instance
-2. Add one or more commands to that registry
+1. Define commands with the typed DSL
+2. Build a `CommandRegistry` from those definitions
 3. Pass the registry to `Citadel`
 
 ```typescript
 import {
   Citadel,
-  CommandRegistry,
-  TextCommandResult,
+  command,
+  createCommandRegistry,
+  text,
 } from "citadel_cli";
 
-// 1. Create the registry
-const registry = new CommandRegistry();
+// 1. Define and register commands
+const registry = createCommandRegistry([
+  command("greet")
+    .describe("Say hello to someone")
+    .arg("name", (arg) => arg.describe("Who are we greeting?"))
+    .handle(async ({ namedArgs }) => text(`Hello ${namedArgs.name} world!`)),
+]);
 
-// 2. Add commands
-registry.addCommand(
-  [
-    { type: "word", name: "greet" },
-    { type: "argument", name: "name", description: "Who are we greeting?" },
-  ],
-  "Say hello to someone", // Description used by the built-in `help` command
-  async (args: string[]) => new TextCommandResult(`Hello ${args[0]} world!`)
-);
-
-// 3. Pass the registry to the component
+// 2. Pass the registry to the component
 function App() {
   return <Citadel commandRegistry={registry} />;
 }
@@ -64,28 +60,68 @@ to the full word. For the above example, typing <kbd>g</kbd> would expand
 in-place to `greet ` (with a trailing space) whereupon you can enter in a value
 for the `name` argument.
 
-## `addCommand` Details
+For hierarchical commands, expansion is prefix-based and unambiguous:
 
-The `addCommand` method has the following signature:
+- `us` can resolve to `user show`
+- `ud` can resolve to `user deactivate`
+- If two options share a prefix (`show` and `search`), continue until unique:
+  `ush` => `user show`, `use` => `user search`
 
-```typescript
-addCommand(segments: CommandSegment[], description: string, handler: CommandHandler): void
-```
+## Help Text
 
-`segments[]` - Each `CommandSegment` in this array consists of a `type` (one of
-"word" or "argument"), a `name`, and an optional `description`
+Argument segment `description` values are shown as argument-level help text.
+Example built-in help output:
 
-`description` - Description of the command itself. Used by the built-in help
-command
+```text
+user show <userId> - Show user details
+  <userId>: Enter user ID
+```
 
-`handler` - What gets executed when <kbd>Enter</kbd> is pressed. The handler
-must return one of the following:
+Handlers must return one of the following:
 
 - `TextCommandResult`
 - `JsonCommandResult`
 - `ImageCommandResult`
 - `ErrorCommandResult`
 
+## Typed DSL
+
+For clearer command authoring, you can define commands with a DSL and compile
+them into a `CommandRegistry`:
+
+```typescript
+import {
+  Citadel,
+  command,
+  createCommandRegistry,
+  text,
+} from "citadel_cli";
+
+const registry = createCommandRegistry([
+  command("user.show")
+    .describe("Show user details")
+    .arg("userId", (arg) => arg.describe("Enter user ID"))
+    .handle(async ({ namedArgs }) => {
+      return text(`Showing user ${namedArgs.userId}`);
+    }),
+]);
+
+function App() {
+  return <Citadel commandRegistry={registry} />;
+}
+```
+
+DSL handlers receive:
+
+- `rawArgs`: positional values (`string[]`)
+- `namedArgs`: argument-name map (`Record<string, string | undefined>`)
+- `commandPath`: dot-delimited path string
+
+## Legacy `addCommand` API
+
+`CommandRegistry#addCommand` still works and is fully supported. The DSL is now
+the recommended authoring path for new command definitions.
+
 ### Arguments
 
 1. Each command can have zero or more arguments
@@ -128,10 +164,12 @@ given below, along with their default values.
 const config = {
   commandTimeoutMs: 10000,
   includeHelpCommand: true,
+  fontFamily: '"JetBrains Mono", monospace',
+  fontSize: '0.875rem', // CSS size (e.g. '14px') or Tailwind class (e.g. 'text-sm')
   maxHeight: '80vh',
   initialHeight: '40vh',
   minHeight: '200',
-  outputFontSize: '0.875rem',
+  outputFontSize: 'text-xs', // optional override for output text only
   resetStateOnHide: false,
   showCitadelKey: '.',
   cursorType: 'blink', // 'blink', 'spin', 'solid', or 'bbs'
@@ -151,79 +189,4 @@ Then to make the component aware of them:
 
 ## Contributing
 
-Contributions are welcome.
-
-1. Clone the repository:
-```bash
-git clone https://github.com/jchilders/citadel_cli.git
-cd citadel_cli
-```
-
-2. Install dependencies:
-```bash
-npm install
-```
-
-3. Build the package:
-```bash
-npm run build
-```
-
-4. (Optional but recommended) Link citadel so you can import it into a parallel project
-```bash
-npm link
-```
-
-5. (Optional) From the directory of the project you want to import Citadel into:
-```bash
-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
-- Before creating a new issue, please check if a similar issue already exists
-- Provide as much detail as possible in bug reports:
-  - Steps to reproduce the issue
-  - Expected behavior
-  - Actual behavior
-  - Browser/environment information
-  - Error messages or screenshots if applicable
-
-### Development Process
-
-1. Fork the repository
-2. Create a new branch for your feature or bugfix:
-   ```bash
-   git checkout -b feature/your-feature-name
-   # or
-   git checkout -b fix/your-bugfix-name
-   ```
-3. Make your changes
-4. Write or update tests as needed
-5. Run the test suite to ensure everything passes:
-   ```bash
-   npm run test
-   ```
-6. Commit your changes with a clear and descriptive commit message
-7. Push to your fork and submit a pull request
-
-### Pull Request Guidelines
-
-- Keep your changes focused. Submit separate pull requests for separate features/fixes
-- Follow the existing code style and conventions
-- Include tests for new functionality
-- Update documentation as needed
-- Ensure all tests pass
-- Describe your changes in detail in the pull request description
-
-### Code Style
-
-- Follow TypeScript best practices
-- Use meaningful variable and function names
-- Comment complex logic or non-obvious code
-- Keep functions focused and modular
-- Use consistent formatting (the project uses ESLint and Prettier)
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on developing, testing, and releasing Citadel CLI.

package/dist/App.test.d.ts

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

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

@@ -25,8 +25,6 @@ export declare const setupCitadelStateHook: () => {
     hook: import('@testing-library/react').RenderHookResult<{
         state: CitadelState;
         actions: CitadelActions;
-        getAvailableCommands_s: () => string[];
-        getAvailableCommandSegments: () => CommandSegment[];
     }, unknown>;
     mockHistory: CommandHistory;
     mockActions: CommandHistoryActions;