command_deck 0.1.0

data/lib/command_deck/assets/js/ui/overlay.js

@@ -0,0 +1,305 @@
+import { el, jsonPretty } from '../core/dom.js';
+import { store } from '../core/store.js';
+import { PositionManager } from './position_manager.js';
+import { ThemeManager } from './theme_manager.js';
+
+export class Overlay {
+  constructor({ mount, panelsApi, actionsApi }) {
+    this.mount = mount;
+    this.panelsApi = panelsApi;
+    this.actionsApi = actionsApi;
+    this._loaded = false;
+  }
+
+  refreshCurrentTab() {
+    // Re-fetch panels and re-render current panel/tab without changing selection
+    this.panelsApi.fetchPanels().then((data) => {
+      const panels = (data && data.panels) || [];
+      this.panels = panels;
+      if (this.panelSelector) this.panelSelector.setPanels(this.panels);
+      const panel = this.panels.find(p => p.key === this.currentPanelKey) || this.panels[0];
+      if (!panel) return;
+      if (this.panelSelector) this.panelSelector.setActiveKey(panel.key);
+      this.renderTabs(panel, this.currentTabIndex || 0);
+    }).catch(() => {/* ignore refresh errors */});
+  }
+
+  init() {
+    if (this._loaded) return; this._loaded = true;
+    // Root pieces
+    this.toggle = el('div', { id: 'command-deck-toggle', title: 'Command Deck' }, ['CD']);
+    this.panel  = el('div', { id: 'command-deck-panel', style: { display: 'none' } });
+    // Keep these nodes across Turbo Drive navigations
+    this.toggle.setAttribute('data-turbo-permanent', '');
+    this.panel.setAttribute('data-turbo-permanent', '');
+
+    const headerWrap = el('div', { id: 'cd-header' });
+    const title = el('h4', null, ['Command Deck']);
+    headerWrap.appendChild(title);
+    const headerRight = el('div', { id: 'cd-header-right' });
+    headerWrap.appendChild(headerRight);
+
+    this.tabsWrap = el('div', { id: 'cd-tabs-wrap' });
+    this.actionsWrap = el('div', { id: 'cd-actions-wrap' });
+    this.resultPre = el('pre', { id: 'command-deck-output' });
+
+    this.panel.appendChild(headerWrap);
+    this.panel.appendChild(this.tabsWrap);
+    this.panel.appendChild(this.actionsWrap);
+    this.panel.appendChild(this.resultPre);
+
+    document.body.appendChild(this.toggle);
+    document.body.appendChild(this.panel);
+
+    this.toggle.addEventListener('click', () => {
+      this.panel.style.display = (this.panel.style.display === 'none' || !this.panel.style.display) ? 'block' : 'none';
+    });
+
+    this.position = new PositionManager(this.toggle, this.panel);
+    this.position.set(this.position.load());
+
+    this.theme = new ThemeManager(this.toggle, this.panel);
+    this.theme.set(this.theme.load());
+  }
+
+  attachSettings(dropdown) {
+    // Append settings into right side of header
+    const headerRight = this.panel.querySelector('#cd-header-right');
+    dropdown.mount(headerRight);
+    if (this.theme) dropdown.setTheme && dropdown.setTheme(this.theme.load());
+  }
+
+  attachPanelSelector(selector) {
+    this.panelSelector = selector;
+    const headerRight = this.panel.querySelector('#cd-header-right');
+    selector.mount(headerRight);
+  }
+
+  loadPanels() {
+    return this.panelsApi.fetchPanels().then(data => this.setPanels(data));
+  }
+
+  setPanels(data) {
+    this.tabsWrap.textContent = '';
+    this.actionsWrap.textContent = '';
+    this.panels = (data && data.panels) || [];
+    if (!this.panels.length) {
+      this.tabsWrap.appendChild(el('div', null, ['No panels defined. Add files under app/command_deck/**/*.rb']))
+      return;
+    }
+    // Initialize selector
+    if (this.panelSelector) {
+      this.panelSelector.setPanels(this.panels);
+    }
+    const saved = store.get('panel-key');
+    const exists = this.panels.find(p => p.key === saved);
+    const key = exists ? saved : this.panels[0].key;
+    this.selectPanel(key);
+  }
+
+  selectPanel(key) {
+    const panel = (this.panels || []).find(p => p.key === key);
+    if (!panel) return;
+    this.currentPanelKey = key;
+    store.set('panel-key', key);
+    if (this.panelSelector) this.panelSelector.setActiveKey(key);
+
+    const headerTitle = this.panel.querySelector('#cd-header h4');
+    headerTitle.textContent = 'Command Deck';
+    this.renderTabs(panel, this.currentTabIndex || 0);
+  }
+
+  renderTabs(panel, selectedIndex = 0) {
+    this.tabsWrap.textContent = '';
+    this.actionsWrap.textContent = '';
+    this.currentTabIndex = selectedIndex;
+    (panel.tabs || []).forEach((tab, i) => {
+      const btn = el('button', { class: 'cd-tab-btn' }, [tab.title]);
+      btn.addEventListener('click', () => { this.currentTabIndex = i; this.renderActions(tab); });
+      this.tabsWrap.appendChild(btn);
+      if (i === selectedIndex) this.renderActions(tab);
+    });
+  }
+
+  renderActions(tab) {
+    this.actionsWrap.textContent = '';
+    (tab.actions || []).forEach(action => {
+      const box = el('div', { class: 'cd-action' });
+      box.appendChild(el('div', { class: 'cd-action-title' }, [action.title]));
+      const form = el('div', { class: 'cd-form' });
+
+      const inputs = {};
+      const paramsMeta = {};
+      (action.params || []).forEach(p => {
+        const labelChildren = [p.label || p.name];
+        if (p.required === true) {
+          labelChildren.push(el('span', { class: 'cd-required', title: 'Required' }, ['*']));
+        }
+        const label = el('label', null, labelChildren);
+        let input;
+        if (p.type === 'boolean') {
+          input = el('input', { type: 'checkbox' });
+        } else if (p.type === 'integer') {
+          input = el('input', { type: 'number', step: '1' });
+        } else if (p.type === 'selector' || (p.choices && p.choices.length)) {
+          input = el('select');
+          if (p.include_blank) {
+            input.appendChild(el('option', { value: '' }, ['']));
+          }
+          (p.choices || []).forEach(ch => {
+            const attrs = { 'data-val': JSON.stringify(ch.value) };
+            if (ch.meta != null) attrs['data-meta'] = JSON.stringify(ch.meta);
+            const opt = el('option', attrs, [ch.label != null ? String(ch.label) : String(ch.value)]);
+            input.appendChild(opt);
+          });
+
+          // Restore last selection (per panel/action/param)
+          const selKey = `sel:${this.currentPanelKey || ''}:${action.key}:${p.name}`;
+          const savedRaw = store.get(selKey);
+          if (savedRaw != null) {
+            let matched = false;
+            for (let i = 0; i < input.options.length; i++) {
+              const o = input.options[i];
+              const raw = o.getAttribute('data-val');
+              if (raw === savedRaw) {
+                input.selectedIndex = i;
+                matched = true;
+                break;
+              }
+            }
+            if (!matched && p.include_blank && savedRaw === '') {
+              for (let i = 0; i < input.options.length; i++) {
+                if (input.options[i].value === '') { input.selectedIndex = i; break; }
+              }
+            }
+          }
+        } else {
+          input = el('input', { type: 'text' });
+        }
+        if (p.required === true && input) {
+          input.setAttribute('aria-required', 'true');
+          input.setAttribute('required', '');
+        }
+        form.appendChild(label);
+        form.appendChild(input);
+
+        // Optional hint below inputs (used for selector current value display)
+        let hint;
+        if (input.tagName === 'SELECT') {
+          hint = el('div', { class: 'cd-param-hint' });
+          const updateHint = () => {
+            const sel = input.options[input.selectedIndex];
+            if (!sel) { hint.textContent = ''; return; }
+            const metaRaw = sel.getAttribute('data-meta');
+            if (!metaRaw) { hint.textContent = ''; return; }
+            try {
+              const meta = JSON.parse(metaRaw);
+              if (typeof meta.enabled === 'boolean') {
+                const status = meta.enabled ? 'ON' : 'OFF';
+                hint.textContent = 'Current: ';
+                const badge = el('span', { class: `cd-badge ${meta.enabled ? 'cd-on' : 'cd-off'}` }, [status]);
+                hint.appendChild(badge);
+              } else {
+                hint.textContent = '';
+              }
+            } catch(_) { hint.textContent = ''; }
+          };
+          input.addEventListener('change', () => {
+            // Persist selection
+            const sel = input.options[input.selectedIndex];
+            const raw = sel ? sel.getAttribute('data-val') : '';
+            const selKey = `sel:${this.currentPanelKey || ''}:${action.key}:${p.name}`;
+            store.set(selKey, raw || '');
+            updateHint();
+            validate();
+          });
+          // Initialize after options are appended
+          setTimeout(updateHint, 0);
+          form.appendChild(hint);
+        }
+
+        inputs[p.name] = input;
+        paramsMeta[p.name] = p;
+      });
+
+      // Validation helpers
+      const requiredParams = (action.params || []).filter(p => p.required === true);
+      const isFilled = (p) => {
+        const inp = inputs[p.name];
+        if (!inp) return false;
+        if (p.type === 'integer') return inp.value !== '';
+        if (p.type === 'selector' || (p.choices && p.choices.length)) {
+          if (p.include_blank) return inp.value !== '' && inp.selectedIndex > -1;
+          return inp.selectedIndex > -1; // any selection counts
+        }
+        if (p.type === 'boolean') return true; // checkbox always provides a value
+        // string or others
+        return String(inp.value || '').trim() !== '';
+      };
+      const validate = () => {
+        const ok = requiredParams.every(isFilled);
+        const running = run.classList.contains('loading');
+        run.disabled = !ok || running;
+      };
+
+      const run = el('button', { class: 'cd-run', title: 'Run' }, ['\u25B6']); // ▶
+      run.addEventListener('click', () => {
+        if (run.disabled) return;
+        run.classList.add('loading');
+        run.setAttribute('aria-busy', 'true');
+        run.disabled = true;
+        const payload = {};
+        Object.keys(inputs).forEach(k => {
+          const inp = inputs[k];
+          const meta = paramsMeta[k] || {};
+          if (inp.tagName === 'SELECT') {
+            const sel = inp.options[inp.selectedIndex];
+            const raw = sel && sel.getAttribute('data-val');
+            const label = sel ? sel.textContent : '';
+            let value;
+            try { value = raw != null ? JSON.parse(raw) : inp.value; } catch(_) { value = inp.value; }
+
+            if (meta.return === 'label') {
+              payload[k] = label;
+            } else if (meta.return === 'both' || meta.return === 'object') {
+              payload[k] = { label: label, value: value };
+            } else {
+              payload[k] = value; // default: value
+            }
+
+            // Persist selection on run as well
+            const selKey = `sel:${this.currentPanelKey || ''}:${action.key}:${k}`;
+            store.set(selKey, raw || '');
+          } else {
+            payload[k] = (inp.type === 'checkbox') ? !!inp.checked : inp.value;
+          }
+        });
+        this.setRunning();
+        this.actionsApi
+          .submit(action.key, payload)
+          .then((res) => { this.setResult(res); this.refreshCurrentTab(); })
+          .catch((e) => this.setResult({ ok:false, error: String(e) }))
+          .finally(() => { run.classList.remove('loading'); run.removeAttribute('aria-busy'); validate(); });
+      });
+      const actionsRow = el('div', { class: 'cd-actions-row' });
+      actionsRow.appendChild(run);
+      form.appendChild(actionsRow);
+
+      box.appendChild(form);
+      this.actionsWrap.appendChild(box);
+
+      // Hook up validation listeners
+      (action.params || []).forEach(p => {
+        const inp = inputs[p.name];
+        if (!inp) return;
+        const evt = (inp.tagName === 'SELECT' || inp.type === 'checkbox') ? 'change' : 'input';
+        inp.addEventListener(evt, validate);
+      });
+      // Initial state
+      validate();
+    });
+  }
+
+  setRunning(){ this.resultPre.textContent = 'Running...'; }
+  setResult(obj){ this.resultPre.textContent = jsonPretty(obj); }
+}

data/lib/command_deck/assets/js/ui/panel_selector.js

@@ -0,0 +1,32 @@
+import { el } from '../core/dom.js';
+
+export class PanelSelector {
+  constructor(onSelect) {
+    this.onSelect = onSelect;
+    this.root = el('div', { id: 'cd-panel-selector' });
+    this.select = el('select');
+    this.root.appendChild(this.select);
+
+    this.select.addEventListener('change', () => {
+      const key = this.select.value;
+      this.onSelect && this.onSelect(key);
+    });
+  }
+
+  mount(container) { container.appendChild(this.root); }
+
+  setPanels(panels) {
+    // panels: [{ key, title, owner, group }]
+    this.select.textContent = '';
+    (panels || []).forEach(p => {
+      const label = [p.group, p.title].filter(Boolean).join(' • ');
+      const opt = el('option', { value: p.key }, [label || p.title || p.key]);
+      this.select.appendChild(opt);
+    });
+  }
+
+  setActiveKey(key) {
+    if (!key) return;
+    this.select.value = key;
+  }
+}

data/lib/command_deck/assets/js/ui/position_manager.js

@@ -0,0 +1,26 @@
+import { store } from '../core/store.js';
+
+const POSITIONS = ['tl','tr','bl','br'];
+
+export class PositionManager {
+  constructor(toggle, panel) {
+    this.toggle = toggle;
+    this.panel = panel;
+  }
+  load() { return store.get('position', 'br'); }
+  save(pos) { store.set('position', pos); }
+  apply(pos) {
+    ['cd-pos-tl','cd-pos-tr','cd-pos-bl','cd-pos-br'].forEach(c => {
+      this.toggle.classList.remove(c);
+      this.panel.classList.remove(c);
+    });
+    const cls = 'cd-pos-' + pos;
+    this.toggle.classList.add(cls);
+    this.panel.classList.add(cls);
+  }
+  set(pos) {
+    if (!POSITIONS.includes(pos)) return;
+    this.save(pos);
+    this.apply(pos);
+  }
+}

data/lib/command_deck/assets/js/ui/settings_dropdown.js

@@ -0,0 +1,64 @@
+import { el } from '../core/dom.js';
+
+export class SettingsDropdown {
+  constructor(onSelectPosition, onThemeChange) {
+    this.onSelectPosition = onSelectPosition;
+    this.onThemeChange = onThemeChange;
+
+    this.root = el('div', { id: 'cd-settings-panel', style: { display: 'none' } });
+    this.button = el('button', { id: 'cd-settings-btn', title: 'Settings' }, ['\u2699']);
+
+    // Position section
+    const titlePos = el('div', { class: 'cd-settings-title' }, ['Position']);
+    const menu = el('div', { class: 'cd-menu' });
+    const items = [
+      ['tl','\u2196  Top-left'],
+      ['tr','\u2197  Top-right'],
+      ['bl','\u2199  Bottom-left'],
+      ['br','\u2198  Bottom-right']
+    ];
+    items.forEach(([key, label]) => {
+      const item = el('button', { class: 'cd-menu-item', 'data-pos': key }, [label]);
+      item.addEventListener('click', (e) => { e.stopPropagation(); this.onSelectPosition(key); this.hide(); });
+      menu.appendChild(item);
+    });
+
+    // Theme toggle (no title/label; just icon button)
+    this.themeBtn = el('button', { id: 'cd-theme-toggle', title: 'Toggle theme' }, ['\u2600']); // sun
+    this.themeBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      const next = (this.currentTheme === 'dark') ? 'light' : 'dark';
+      this.setTheme(next);
+      this.onThemeChange && this.onThemeChange(next);
+    });
+
+    this.root.appendChild(titlePos);
+    this.root.appendChild(menu);
+    this.root.appendChild(this.themeBtn);
+
+    this.button.addEventListener('click', (e) => {
+      e.stopPropagation();
+      this.toggle();
+    });
+    this.root.addEventListener('click', (e) => e.stopPropagation());
+    document.addEventListener('click', () => this.hide());
+  }
+
+  setTheme(theme) {
+    this.currentTheme = theme === 'dark' ? 'dark' : 'light';
+    if (this.themeBtn) this.themeBtn.textContent = (this.currentTheme === 'dark') ? '\u263D' : '\u2600';
+    // ☽ (U+263D) for moon, ☀ (U+2600) for sun
+  }
+
+  mount(container) {
+    container.appendChild(this.button);
+    container.appendChild(this.root);
+  }
+
+  toggle() {
+    const willOpen = (this.root.style.display === 'none' || !this.root.style.display);
+    this.root.style.display = willOpen ? 'block' : 'none';
+    this.button.classList.toggle('open', willOpen);
+  }
+  hide() { this.root.style.display = 'none'; this.button.classList.remove('open'); }
+}

data/lib/command_deck/assets/js/ui/theme_manager.js

@@ -0,0 +1,34 @@
+import { store } from '../core/store.js';
+
+export class ThemeManager {
+  constructor(toggle, panel) {
+    this.toggle = toggle;
+    this.panel = panel;
+  }
+
+  load() {
+    const saved = store.get('theme');
+    if (saved) return saved;
+    try {
+      if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+        return 'dark';
+      }
+    } catch(_) {}
+    return 'light';
+  }
+
+  save(theme) { store.set('theme', theme); }
+
+  apply(theme) {
+    const isDark = theme === 'dark';
+    [this.toggle, this.panel].forEach(node => {
+      node.classList.toggle('cd-theme-dark', isDark);
+    });
+  }
+
+  set(theme) {
+    if (theme !== 'light' && theme !== 'dark') return;
+    this.save(theme);
+    this.apply(theme);
+  }
+}

data/lib/command_deck/engine.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+require_relative "middleware"
+
+module CommandDeck
+  # Rails engine for Command Deck
+  class Engine < ::Rails::Engine
+    isolate_namespace CommandDeck
+
+    initializer "command_deck.mount_point" do
+      # Default mount point. If the host app has a relative_url_root, respect it.
+      mp = "/command_deck"
+      if defined?(Rails) && Rails.application.config.respond_to?(:relative_url_root)
+        root = Rails.application.config.relative_url_root
+        mp = File.join(root, mp) if root.present?
+      end
+      CommandDeck::Middleware.mount_point = mp
+    end
+
+    initializer "command_deck.middleware" do |app|
+      # Dev-only injection. Safe no-op in other environments.
+      if defined?(Rails) && Rails.env.development?
+        app.middleware.insert_after ActionDispatch::DebugExceptions, CommandDeck::Middleware
+      end
+    end
+  end
+end

data/lib/command_deck/executor.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module CommandDeck
+  # Executor for running actions
+  class Executor
+    def self.call(key:, params:)
+      action = Registry.find_action(key)
+      raise ArgumentError, "Unknown action #{key}" unless action
+
+      coerced = coerce(action.params, params || {})
+      action.block.call(coerced, {})
+    end
+
+    def self.coerce(schema, raw)
+      return {} if schema.nil? || schema.empty?
+
+      schema.each_with_object({}) do |param, out|
+        name = param[:name]
+        value = raw[name] || raw[name.to_s]
+        out[name] = coerce_value(param[:type], value)
+      end
+    end
+
+    def self.coerce_value(type, value)
+      case type
+      when :boolean then coerce_boolean(value)
+      when :integer then coerce_integer(value)
+      when :selector then coerce_selector(value)
+      else coerce_string(value)
+      end
+    end
+
+    def self.coerce_boolean(value)
+      boolean_true?(value)
+    end
+
+    def self.coerce_integer(value)
+      integer_or_nil(value)
+    end
+
+    def self.coerce_selector(value)
+      return symbolize_keys_shallow(value) if value.is_a?(Hash)
+
+      value
+    end
+
+    def self.coerce_string(value)
+      value&.to_s
+    end
+
+    def self.symbolize_keys_shallow(hash)
+      hash.each_with_object({}) do |(k, v), out|
+        key = k.respond_to?(:to_sym) ? k.to_sym : k
+        out[key] = v
+      end
+    end
+
+    def self.boolean_true?(value)
+      return false if value.nil?
+
+      value == true || %w[true 1 on].include?(value.to_s.strip.downcase)
+    end
+
+    def self.integer_or_nil(value)
+      return nil if value.nil? || value == ""
+
+      value.to_i
+    end
+  end
+end

data/lib/command_deck/injector.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Minimal response body injector adapted from the web-console project (MIT License).
+# It safely appends content before </body> when present and adjusts Content-Length.
+module CommandDeck
+  # Tiny middleware that injects a tiny floating UI into HTML responses.
+  class Injector
+    def initialize(body, headers)
+      @body = "".dup
+      body.each { |part| @body << part }
+      body.close if body.respond_to?(:close)
+      @headers = headers
+    end
+
+    def inject(content)
+      @headers[Rack::CONTENT_LENGTH] = (@body.bytesize + content.bytesize).to_s if @headers[Rack::CONTENT_LENGTH]
+
+      [
+        if (position = @body.rindex("</body>"))
+          [@body.insert(position, content)]
+        else
+          [@body << content]
+        end,
+        @headers
+      ]
+    end
+  end
+end

data/lib/command_deck/middleware.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "rack"
+require_relative "injector"
+
+module CommandDeck
+  # Dev-only middleware that injects a tiny floating UI into HTML responses.
+  class Middleware
+    class << self
+      attr_accessor :mount_point
+    end
+    self.mount_point = "/command_deck"
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+
+      begin
+        return [status, headers, body] unless html_response?(headers)
+        return [status, headers, body] if engine_request?(env)
+
+        body, headers = Injector.new(body, headers).inject(overlay_snippet)
+        [status, headers, body]
+      rescue StandardError
+        # Fail open: on any injection error, return original response
+        [status, headers, body]
+      end
+    end
+
+    private
+
+    def html_response?(headers)
+      ctype = headers[Rack::CONTENT_TYPE].to_s
+      return true if ctype.empty?
+
+      ctype.include?("html")
+    end
+
+    def engine_request?(env)
+      path = env["PATH_INFO"].to_s
+      path.start_with?(self.class.mount_point)
+    end
+
+    def overlay_snippet
+      mp = self.class.mount_point
+      <<~HTML
+        <!-- Command Deck assets (ESM) -->
+        <link rel="stylesheet" href="#{mp}/assets/css/main.css" />
+        <script type="module" src="#{mp}/assets/js/main.js" data-mount="#{mp}"></script>
+        <!-- /Command Deck assets -->
+      HTML
+    end
+  end
+end

data/lib/command_deck/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module CommandDeck
+  # Rails engine for Command Deck
+  class Railtie < ::Rails::Railtie
+    initializer "command_deck.load_panels", after: :load_config_initializers do
+      path = Rails.root.join("app/command_deck")
+      Dir[path.join("**/*.rb")].sort.each { |f| load f } if Dir.exist?(path)
+    end
+  end
+end