citadel_cli 1.4.0 → 1.4.2

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)
+
+Commands are the core concept in Citadel. Think `user add 1234` or
+`qa deploy my_feature_branch`.
 
-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:
+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
@@ -170,8 +211,11 @@ const config = {
   initialHeight: '50vh',
   minHeight: '200',
   outputFontSize: '0.75rem', // optional CSS font-size override for output text
+  showOutputPane: true, // set false to hide command output pane
   resetStateOnHide: false,
+  closeOnEscape: true,
   showCitadelKey: '.',
+  showOnLoad: false,
   cursorType: 'blink', // 'blink', 'spin', 'solid', or 'bbs'
   cursorSpeed: 530,
   storage: {

package/dist/citadel.css

@@ -0,0 +1,472 @@
+: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;
+}