citadel_cli 1.3.0 → 1.4.1

package/README.md

@@ -1,28 +1,43 @@
 # Citadel CLI
 
-A keyboard-first command console for the power users of your web apps.
+Embed a terminal-style command console directly inside your React app.
 
-# Use Cases
+Citadel helps you turn repetitive UI workflows into fast keyboard commands for
+developers, support engineers, and power users, without sending them to a
+separate admin tool.
 
-- **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.
+## Why Developers Add Citadel
+
+- **Move faster in existing apps**: expose internal actions as commands instead
+  of building more buttons and forms
+- **Debug in context**: call APIs, inspect JSON, clear storage, and run app
+  actions without leaving the page
+- **Keep UI clean**: hidden-by-default overlay (toggle key is configurable;
+  default is `.`, and can be shown on load if desired)
+- **Scale safely**: typed command DSL with argument help, async handlers, and
+  structured result rendering (`text`, `json`, `image`, `error`, `bool`)
+
+## Common Use Cases
+
+- **Internal Tools**: replace repetitive click paths with direct commands
+- **Support & Operations**: add safe operational commands to admin dashboards
+- **API Testing & Debugging**: execute REST calls and inspect responses inline
+- **Power User Workflows**: give advanced users terminal speed in web UI
 
 ![Animated screenshot of Citadel CLI](https://github.com/user-attachments/assets/b64da0f7-a4a0-4f76-bc03-c0e40c0e14e5)
 
-# Installation
+## Installation
 
 ```bash
 npm i citadel_cli
 ```
 
-## "Hello world" Example
+## Quick Start (Hello World)
 
-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:
+Commands are the core concept in Citadel. Think `user add 1234` or
+`qa deploy my_feature_branch`.
+
+To get running:
 
 1. Define commands with the typed DSL
 2. Build a `CommandRegistry` from those definitions
@@ -83,6 +98,7 @@ Handlers must return one of the following:
 - `JsonCommandResult`
 - `ImageCommandResult`
 - `ErrorCommandResult`
+- `BooleanCommandResult`
 
 ## Typed DSL
 
@@ -117,6 +133,31 @@ DSL handlers receive:
 - `namedArgs`: argument-name map (`Record<string, string | undefined>`)
 - `commandPath`: dot-delimited path string
 
+Helper constructors exported by the DSL:
+
+- `text(value)`
+- `json(value)`
+- `image(url, altText?)`
+- `error(message)`
+- `bool(value, trueText?, falseText?)`
+
+### Boolean Result Example
+
+```typescript
+import { command, createCommandRegistry, bool } from "citadel_cli";
+
+const registry = createCommandRegistry([
+  command("bool.random")
+    .describe("Return a random boolean")
+    .handle(async () => bool(Math.random() >= 0.5, "👍", "👎")),
+]);
+```
+
+Demo registries include boolean commands:
+
+- Basic example: `bool.true`, `bool.false`, `bool.random`
+- DevOps example: `bool.deploy.window`, `bool.error.budget.healthy`, `bool.autoscale.recommended`
+
 ## Legacy `addCommand` API
 
 `CommandRegistry#addCommand` still works and is fully supported. The DSL is now
@@ -165,13 +206,15 @@ 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')
+  fontSize: '0.875rem', // CSS font-size value (e.g. '14px', '0.875rem')
   maxHeight: '80vh',
-  initialHeight: '40vh',
+  initialHeight: '50vh',
   minHeight: '200',
-  outputFontSize: 'text-xs', // optional override for output text only
+  outputFontSize: '0.75rem', // optional CSS font-size override for output text
   resetStateOnHide: false,
+  closeOnEscape: true,
   showCitadelKey: '.',
+  showOnLoad: false,
   cursorType: 'blink', // 'blink', 'spin', 'solid', or 'bbs'
   cursorSpeed: 530,
   storage: {
@@ -187,6 +230,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"
   }
 }

package/dist/citadel.css

@@ -1 +1,472 @@
-._panelContainer_1pav9_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_1pav9_19{height:100%;flex:1;width:100%;display:flex;flex-direction:column;margin:0;padding:0}._inputSection_1pav9_29{border-top:1px solid var(--citadel-border);padding:1rem;margin:0;box-sizing:border-box}._resizeHandle_1pav9_36{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_1pav9_36:hover{background:#ffffff1a}@keyframes _citadel_slideUp_1pav9_65{0%{transform:translateY(100%)}to{transform:translateY(0)}}@keyframes _citadel_slideDown_1pav9_69{0%{transform:translateY(0)}to{transform:translateY(100%)}}._citadel_slideUp_1pav9_65{animation:_citadel_slideUp_1pav9_65 .2s ease-out forwards}._citadel_slideDown_1pav9_69{animation:_citadel_slideDown_1pav9_69 .2s ease-out forwards}._inlineContainer_1pav9_73{position:relative;width:100%;height:100%;display:flex;flex-direction:column;background-color:var(--citadel-bg);overflow:hidden;box-sizing:border-box}
+:host {
+  --citadel-bg: oklch(20.8% 0.042 265.8);
+  --citadel-surface: oklch(27.9% 0.041 260);
+  --citadel-border: oklch(37.2% 0.044 257.3);
+  --citadel-text: oklch(92.8% 0.006 264.5);
+  --citadel-muted: oklch(70.7% 0.022 261.3);
+  --citadel-subtle: oklch(55.1% 0.023 264.4);
+  --citadel-word: oklch(70.7% 0.165 254.6);
+  --citadel-arg: oklch(72.3% 0.219 149.6);
+  --citadel-error: oklch(70.4% 0.191 22.2);
+  --citadel-success: oklch(72.3% 0.219 149.6);
+  --citadel-min-height: 200px;
+  --citadel-max-height: 80vh;
+  --citadel-default-height: 35vh;
+  --citadel-panel-enter-duration: 200ms;
+  --citadel-panel-exit-duration: 200ms;
+  --citadel-panel-enter-easing: cubic-bezier(0.16, 1, 0.3, 1);
+  --citadel-panel-exit-easing: cubic-bezier(0.4, 0, 1, 1);
+
+  display: block;
+  pointer-events: auto;
+  color: var(--citadel-text);
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+:host([data-display-mode='panel']) {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  width: 100%;
+  height: var(--citadel-default-height);
+  max-height: var(--citadel-max-height);
+  min-height: var(--citadel-min-height);
+  z-index: 2147483647;
+  overflow: hidden;
+}
+
+:host([data-display-mode='inline']) {
+  position: relative;
+  bottom: auto;
+  left: auto;
+  right: auto;
+  z-index: auto;
+  width: 100%;
+  height: 100%;
+  max-height: none;
+  min-height: 0;
+  overflow: hidden;
+}
+
+#citadel-root {
+  width: 100%;
+  height: 100%;
+}
+
+#citadel-root,
+#citadel-root * {
+  box-sizing: border-box;
+}
+
+.panelContainer {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  width: 100%;
+  height: var(--citadel-default-height);
+  min-height: var(--citadel-min-height);
+  max-height: var(--citadel-max-height);
+  margin: 0;
+  padding: 0;
+  background-color: var(--citadel-bg);
+  overflow: hidden;
+  transform: translateY(0);
+  will-change: transform;
+}
+
+.innerContainer {
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+}
+
+.citadel-tty {
+  background: var(--citadel-bg);
+}
+
+.citadel-tty-output-pane {
+  display: flex;
+  flex: 1 1 auto;
+  min-height: 0;
+  padding: 0.75rem 1rem 0;
+}
+
+.citadel-tty-input-region {
+  flex-shrink: 0;
+}
+
+.resizeHandle {
+  position: absolute;
+  top: -3px;
+  left: 0;
+  right: 0;
+  z-index: 10;
+  width: 100%;
+  height: 6px;
+  background: transparent;
+  cursor: ns-resize;
+  user-select: none;
+  -webkit-user-select: none;
+  pointer-events: all;
+}
+
+.resizeHandle:hover {
+  background: color-mix(in oklch, var(--citadel-text) 10%, transparent);
+}
+
+@keyframes citadel_slideUp {
+  from {
+    transform: translateY(100%);
+  }
+
+  to {
+    transform: translateY(0);
+  }
+}
+
+@keyframes citadel_slideDown {
+  from {
+    transform: translateY(0);
+  }
+
+  to {
+    transform: translateY(100%);
+  }
+}
+
+.citadel_slideUp {
+  animation: citadel_slideUp var(--citadel-panel-enter-duration) var(--citadel-panel-enter-easing) forwards;
+}
+
+.citadel_slideDown {
+  animation: citadel_slideDown var(--citadel-panel-exit-duration) var(--citadel-panel-exit-easing) forwards;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :host {
+    --citadel-panel-enter-duration: 1ms;
+    --citadel-panel-exit-duration: 1ms;
+  }
+}
+
+.inlineContainer {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  background-color: var(--citadel-bg);
+  overflow: hidden;
+}
+
+.citadel-output {
+  width: 100%;
+  height: 100%;
+  overflow-y: auto;
+  padding: 0.75rem;
+  border: 1px solid var(--citadel-border);
+  border-radius: 0.5rem;
+  background: color-mix(in oklch, var(--citadel-bg) 75%, black);
+  text-align: left;
+}
+
+.citadel-output-item {
+  margin-bottom: 1rem;
+}
+
+.citadel-output-item:last-child {
+  margin-bottom: 0;
+}
+
+.citadel-output-content {
+  margin-top: 0.35rem;
+  color: var(--citadel-text);
+}
+
+.citadel-output-content > :first-child {
+  margin-top: 0;
+}
+
+.citadel-output-content > :last-child {
+  margin-bottom: 0;
+}
+
+.citadel-output-line {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.citadel-output-command,
+.citadel-output-command-word {
+  color: var(--citadel-text);
+}
+
+.citadel-output-command-arg {
+  color: var(--citadel-arg);
+}
+
+.citadel-output-separator {
+  color: var(--citadel-muted);
+}
+
+.citadel-output-timestamp {
+  color: var(--citadel-subtle);
+}
+
+.citadel-status-dot {
+  width: 1rem;
+  height: 1rem;
+  border-radius: 999px;
+}
+
+.citadel-status-dot-success {
+  background: var(--citadel-success);
+}
+
+.citadel-status-dot-failure {
+  background: var(--citadel-error);
+}
+
+.citadel-spinner {
+  width: 1rem;
+  height: 1rem;
+  border: 2px solid color-mix(in oklch, var(--citadel-text) 60%, transparent);
+  border-top-color: color-mix(in oklch, var(--citadel-muted) 80%, black);
+  border-radius: 999px;
+  animation: citadel-spin 0.9s linear infinite;
+}
+
+@keyframes citadel-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.citadel-input-shell {
+  width: 100%;
+  padding: 1rem;
+  border-radius: 0.5rem;
+  background-color: var(--citadel-bg);
+}
+
+.citadel-input-line {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.citadel-input-prompt {
+  color: var(--citadel-muted);
+}
+
+.citadel-input-row {
+  display: flex;
+  align-items: center;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.citadel-input-segments {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+}
+
+.citadel-input-segment-arg {
+  color: var(--citadel-text);
+  white-space: pre;
+}
+
+.citadel-input-segment-word {
+  color: var(--citadel-word);
+  white-space: pre;
+}
+
+.citadel-input-segment-space {
+  color: var(--citadel-text);
+  white-space: pre;
+}
+
+.citadel-input-segment-space-command {
+  color: var(--citadel-word);
+}
+
+.citadel-input-control {
+  position: relative;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.citadel-input-measure {
+  position: absolute;
+  top: 0;
+  left: 0;
+  visibility: hidden;
+  pointer-events: none;
+  white-space: pre;
+  font: inherit;
+  letter-spacing: inherit;
+}
+
+.citadel-input-field {
+  width: 100%;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  outline: none;
+  background: transparent;
+  font: inherit;
+  line-height: inherit;
+  letter-spacing: inherit;
+  appearance: none;
+  -webkit-appearance: none;
+  caret-color: transparent;
+}
+
+.citadel-input-field::placeholder {
+  color: var(--citadel-subtle);
+  opacity: 1;
+}
+
+.citadel-input-field.is-command-mode {
+  color: var(--citadel-word);
+}
+
+.citadel-input-field.is-argument-mode {
+  color: var(--citadel-text);
+}
+
+.citadel-input-cursor {
+  position: absolute;
+  top: 0;
+  pointer-events: none;
+}
+
+@keyframes citadel-invalid-glow {
+  0%,
+  100% {
+    box-shadow: 0 0 0 color-mix(in oklch, var(--citadel-error) 0%, transparent);
+  }
+
+  50% {
+    box-shadow: 0 0 8px color-mix(in oklch, var(--citadel-error) 70%, transparent);
+  }
+}
+
+.invalid-input-animation {
+  animation: citadel-invalid-glow 0.4s ease-in-out;
+}
+
+.citadel-cursor-wrapper {
+  position: relative;
+  display: inline-block;
+}
+
+.command-cursor {
+  display: inline-block;
+  white-space: pre;
+}
+
+@keyframes citadel-shake {
+  0%,
+  100% {
+    transform: translateX(0);
+  }
+
+  25% {
+    transform: translateX(-4px);
+  }
+
+  75% {
+    transform: translateX(4px);
+  }
+}
+
+.animate-shake {
+  animation: citadel-shake 0.2s ease-in-out;
+}
+
+.citadel-available-commands {
+  margin-top: 0.5rem;
+  padding: 0.5rem 1rem;
+  border-top: 1px solid var(--citadel-border);
+}
+
+.citadel-available-commands-content {
+  color: var(--citadel-muted);
+}
+
+.citadel-available-chip-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.citadel-available-chip {
+  padding: 0.25rem 0.5rem;
+  border-radius: 0.375rem;
+  background: var(--citadel-surface);
+}
+
+.citadel-available-chip-text {
+  color: white;
+}
+
+.citadel-available-chip-prefix {
+  text-decoration: underline;
+}
+
+.citadel-available-next-arg {
+  color: var(--citadel-word);
+}
+
+.citadel-available-next-desc {
+  margin-left: 0.5rem;
+  color: var(--citadel-muted);
+}
+
+.citadel-result-json,
+.citadel-result-text {
+  color: var(--citadel-text);
+}
+
+.citadel-result-json {
+  margin: 0;
+}
+
+.citadel-result-text {
+  white-space: pre;
+}
+
+.citadel-result-error {
+  margin-top: 0.25rem;
+  color: var(--citadel-error);
+}
+
+.citadel-result-pending {
+  color: var(--citadel-muted);
+}
+
+.citadel-result-image-wrap {
+  margin-block: 0.5rem;
+}
+
+.citadel-result-image {
+  max-width: 400px;
+  max-height: 300px;
+  height: auto;
+  object-fit: contain;
+  border-radius: 0.5rem;
+}