citadel_cli 1.1.7 → 1.4.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 font-size value (e.g. '14px', '0.875rem')
   maxHeight: '80vh',
-  initialHeight: '40vh',
+  initialHeight: '50vh',
   minHeight: '200',
-  outputFontSize: '0.875rem',
+  outputFontSize: '0.75rem', // optional CSS font-size override for output text
   resetStateOnHide: false,
   showCitadelKey: '.',
   cursorType: 'blink', // 'blink', 'spin', 'solid', or 'bbs'
@@ -149,6 +187,64 @@ Then to make the component aware of them:
 <Citadel commandRegistry={cmdRegistry} config={config} />
 ```
 
+## Performance Metrics
+
+Citadel includes scripts to capture and compare before/after performance and
+size metrics.
+
+### Metrics collected
+
+- Build metrics:
+  - Bundle size (raw + gzip) for `dist/citadel.es.js`, `dist/citadel.umd.cjs`,
+    and `dist/citadel.css`
+  - Total LOC and extension breakdown
+  - Dependency presence for `tailwindcss`, `postcss`, and `autoprefixer`
+  - `node_modules` size (`du -sk`)
+- Runtime metrics (Chromium):
+  - JS heap usage before/after interaction
+  - Input latency (keydown to input update)
+  - FPS sample over a short window
+  - Long task count and duration
+  - DOM node count
+
+All outputs are written to `test-results/metrics/`.
+
+### Commands
+
+```bash
+npm run metrics:build
+npm run metrics:runtime
+npm run metrics:compare -- --before <before.json> --after <after.json>
+npm run metrics:all -- --label <label>
+npm run metrics:report -- --label <label> --before-build <before-build.json> --before-runtime <before-runtime.json>
+```
+
+### Before/After workflow
+
+1. Capture a baseline snapshot:
+
+```bash
+npm run metrics:all -- --label before
+```
+
+2. After your changes, capture the new snapshot and generate comparisons:
+
+```bash
+npm run metrics:all -- --label after \
+  --before-build test-results/metrics/build-before-<timestamp>.json \
+  --before-runtime test-results/metrics/runtime-before-<timestamp>.json
+```
+
+3. Open generated reports:
+- `test-results/metrics/run-after.md`
+- `test-results/metrics/compare-build-after.md` (if `--before-build` provided)
+- `test-results/metrics/compare-runtime-after.md` (if `--before-runtime` provided)
+
+Notes:
+- `metrics:runtime` starts a local dev server and requires local port binding.
+- If you only want comparison output from existing snapshots, use
+  `npm run metrics:report`.
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on developing, testing, and releasing Citadel CLI.

package/dist/.vite/manifest.json

@@ -4,9 +4,5 @@
     "name": "index",
     "src": "src/index.ts",
     "isEntry": true
-  },
-  "style.css": {
-    "file": "citadel.css",
-    "src": "style.css"
   }
 }