kb-dashboard-cli 0.2.0__tar.gz

kb_dashboard_cli-0.2.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.3
+Name: kb-dashboard-cli
+Version: 0.2.0
+Summary: CLI, LSP, and future MCP server for kb-yaml-to-lens dashboard compiler
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Dist: kb-dashboard-core
+Requires-Dist: kb-dashboard-tools
+Requires-Dist: click>=8.3
+Requires-Dist: rich-click>=1.9.0
+Requires-Dist: elasticsearch>=8.16.2
+Requires-Dist: pygls>=2.0.0
+Requires-Dist: lsprotocol>=2024.0.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+<!-- markdownlint-disable MD041 -->
+![project-banner-smaller](https://github.com/user-attachments/assets/2cf8c18b-32e1-4b32-9a15-41f0d0d657f7)
+
+# kb-dashboard-cli
+
+CLI, LSP, and future MCP server for the kb-yaml-to-lens dashboard compiler.
+
+This package provides command-line tools and language server capabilities for building Kibana dashboards from YAML definitions.
+It converts human-friendly YAML dashboard definitions into Kibana NDJSON format:
+
+## Features
+
+- **YAML-based Dashboard Definition** – Define dashboards, panels, filters, and queries in simple YAML
+- **Rich Panel Support** – Lens visualizations (metric, pie, XY charts), Markdown, Links, Image panels, and more
+- **Advanced Controls** – Control groups with options lists, range sliders, and time sliders with chaining
+- **Filter Support** – Exists, phrase, range, and custom DSL with AND/OR/NOT operators
+- **Direct Upload** – Optional direct upload to Kibana with authentication support
+
+## Prerequisites
+
+**For ⭐ VS Code Extension (Recommended):**
+- VS Code 1.85.0+ or compatible editor (Cursor, VSCodium, etc.)
+- No Python installation required - bundled binary included!
+
+**For CLI (Automation/CI):**
+- Python 3.12+
+- [uv](https://github.com/astral-sh/uv) (recommended for dependency management)
+
+## Quick Start
+
+### Option 1: ⭐ VS Code Extension (Recommended for Getting Started)
+
+**Best for:** Interactive dashboard development, visual editing, live preview
+
+The VS Code extension is the fastest way to start building Kibana dashboards. It includes:
+- Pre-built snippets for quick dashboard scaffolding
+- Live preview as you type
+- Visual drag-and-drop grid editor
+- One-click upload to Kibana
+- **No Python installation required** - LSP server binary is bundled
+
+#### Installation
+
+**From OpenVSX Registry (Cursor, VS Code forks):**
+1. Open Extensions view (Ctrl+Shift+X)
+2. Search for "Kibana Dashboard Compiler"
+3. Click Install
+
+**Manual VSIX Install:**
+Download platform-specific `.vsix` from [releases page](https://github.com/strawgate/kb-yaml-to-lens/releases)
+
+#### Verify Installation
+
+After installation, verify the extension is working:
+
+1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
+2. Type "YAML Dashboard" - you should see all extension commands
+3. Create a test file: `test-dashboard.yaml`
+4. Type `dashboard` and press Tab - a snippet should insert
+
+If commands don't appear, restart VS Code and check the Output panel (View → Output → "Kibana Dashboard Compiler").
+
+#### Your First Dashboard in VS Code
+
+1. Create a new file: `my-dashboard.yaml`
+2. Start typing `dashboard` and press Tab to insert snippet
+3. Save (Ctrl+S) - auto-compiles in background
+4. Run command (Ctrl+Shift+P): **"YAML Dashboard: Preview Dashboard"**
+5. Configure Kibana URL in settings, then run: **"YAML Dashboard: Open in Kibana"**
+
+**Learn more:** [VS Code Extension Documentation](https://strawgate.github.io/kb-yaml-to-lens/vscode-extension)
+
+---
+
+### Option 2: CLI (Best for Automation & CI/CD)
+
+**Best for:** Scripting, CI/CD pipelines, batch processing, programmatic usage
+
+The CLI provides three installation methods:
+
+<details>
+<summary><b>Click to expand CLI installation options</b></summary>
+
+#### Using uv (Recommended for Development)
+
+This project uses [uv](https://github.com/astral-sh/uv) for fast, reliable Python package management.
+
+**For basic usage (compiling dashboards):**
+
+```bash
+uv sync
+```
+
+#### Using Docker
+
+Run the compiler in a container without installing Python or dependencies:
+
+```bash
+# Pull the pre-built image
+docker pull ghcr.io/strawgate/kb-yaml-to-lens/kb-dashboard-compiler:latest
+
+# Or build locally (from repo root)
+make cli docker-build
+```
+
+#### Standalone Binary
+
+Download a platform-specific binary from the [releases page](https://github.com/strawgate/kb-yaml-to-lens/releases):
+
+- Linux (x64): `kb-dashboard-linux-x64`
+- macOS (Intel): `kb-dashboard-darwin-x64`
+- macOS (Apple Silicon): `kb-dashboard-darwin-arm64`
+- Windows (x64): `kb-dashboard-windows-x64.exe`
+
+No Python installation required!
+
+</details>
+
+#### Compile Your First Dashboard (CLI)
+
+1. Create a YAML dashboard file in `inputs/` directory:
+
+```yaml
+dashboards:
+- name: My First Dashboard
+  description: A simple dashboard with markdown
+  panels:
+    - title: Welcome
+      grid: { x: 0, y: 0, w: 24, h: 15 }  # Position and size on 48-column grid
+      markdown:
+        content: |
+          # Welcome to Kibana!
+
+          This is my first dashboard compiled from YAML.
+```
+
+2. Compile to NDJSON:
+
+If using uv: `uv run kb-dashboard compile --input-dir inputs --output-dir output`
+
+If using Docker:
+```bash
+docker run --rm -v $(pwd)/inputs:/inputs -v $(pwd)/output:/output \
+  ghcr.io/strawgate/kb-yaml-to-lens/kb-dashboard-compiler:latest \
+  compile --input-dir inputs --output-dir output
+```
+
+If using standalone binary: `./kb-dashboard-<platform> compile --input-dir inputs --output-dir output`
+
+3. (Optional) Upload directly to Kibana:
+
+Add `--upload --kibana-url http://localhost:5601 --kibana-username elastic --kibana-password changeme` to the compile command above.
+
+The `--upload` flag will automatically open your dashboard in the browser upon successful upload.
+
+**Learn more:** [CLI Documentation](https://strawgate.github.io/kb-yaml-to-lens/CLI)
+
+## Documentation
+
+### Getting Started
+- **[VS Code Extension Guide](https://strawgate.github.io/kb-yaml-to-lens/vscode-extension)** - Visual dashboard development (recommended for beginners)
+- **[CLI Reference](https://strawgate.github.io/kb-yaml-to-lens/CLI)** - Command-line compilation and automation
+- **[Complete Examples](https://strawgate.github.io/kb-yaml-to-lens/examples/)** - Real-world dashboard examples you can copy
+
+### Deep Dive
+- **[Full Documentation Site](https://strawgate.github.io/kb-yaml-to-lens/)** - Complete user guide and API reference
+- **[Programmatic Usage Guide](https://strawgate.github.io/kb-yaml-to-lens/programmatic-usage)** - Create dashboards entirely in Python code
+- **[Architecture](https://strawgate.github.io/kb-yaml-to-lens/architecture)** - Technical design and data flow overview
+- **[Contributing Guide](../CONTRIBUTING.md)** - How to contribute and add new capabilities
+
+## License
+
+MIT
+
+## Support
+
+For issues and feature requests, please refer to the repository's issue tracker.

kb_dashboard_cli-0.2.0/README.md

@@ -0,0 +1,177 @@
+<!-- markdownlint-disable MD041 -->
+![project-banner-smaller](https://github.com/user-attachments/assets/2cf8c18b-32e1-4b32-9a15-41f0d0d657f7)
+
+# kb-dashboard-cli
+
+CLI, LSP, and future MCP server for the kb-yaml-to-lens dashboard compiler.
+
+This package provides command-line tools and language server capabilities for building Kibana dashboards from YAML definitions.
+It converts human-friendly YAML dashboard definitions into Kibana NDJSON format:
+
+## Features
+
+- **YAML-based Dashboard Definition** – Define dashboards, panels, filters, and queries in simple YAML
+- **Rich Panel Support** – Lens visualizations (metric, pie, XY charts), Markdown, Links, Image panels, and more
+- **Advanced Controls** – Control groups with options lists, range sliders, and time sliders with chaining
+- **Filter Support** – Exists, phrase, range, and custom DSL with AND/OR/NOT operators
+- **Direct Upload** – Optional direct upload to Kibana with authentication support
+
+## Prerequisites
+
+**For ⭐ VS Code Extension (Recommended):**
+- VS Code 1.85.0+ or compatible editor (Cursor, VSCodium, etc.)
+- No Python installation required - bundled binary included!
+
+**For CLI (Automation/CI):**
+- Python 3.12+
+- [uv](https://github.com/astral-sh/uv) (recommended for dependency management)
+
+## Quick Start
+
+### Option 1: ⭐ VS Code Extension (Recommended for Getting Started)
+
+**Best for:** Interactive dashboard development, visual editing, live preview
+
+The VS Code extension is the fastest way to start building Kibana dashboards. It includes:
+- Pre-built snippets for quick dashboard scaffolding
+- Live preview as you type
+- Visual drag-and-drop grid editor
+- One-click upload to Kibana
+- **No Python installation required** - LSP server binary is bundled
+
+#### Installation
+
+**From OpenVSX Registry (Cursor, VS Code forks):**
+1. Open Extensions view (Ctrl+Shift+X)
+2. Search for "Kibana Dashboard Compiler"
+3. Click Install
+
+**Manual VSIX Install:**
+Download platform-specific `.vsix` from [releases page](https://github.com/strawgate/kb-yaml-to-lens/releases)
+
+#### Verify Installation
+
+After installation, verify the extension is working:
+
+1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
+2. Type "YAML Dashboard" - you should see all extension commands
+3. Create a test file: `test-dashboard.yaml`
+4. Type `dashboard` and press Tab - a snippet should insert
+
+If commands don't appear, restart VS Code and check the Output panel (View → Output → "Kibana Dashboard Compiler").
+
+#### Your First Dashboard in VS Code
+
+1. Create a new file: `my-dashboard.yaml`
+2. Start typing `dashboard` and press Tab to insert snippet
+3. Save (Ctrl+S) - auto-compiles in background
+4. Run command (Ctrl+Shift+P): **"YAML Dashboard: Preview Dashboard"**
+5. Configure Kibana URL in settings, then run: **"YAML Dashboard: Open in Kibana"**
+
+**Learn more:** [VS Code Extension Documentation](https://strawgate.github.io/kb-yaml-to-lens/vscode-extension)
+
+---
+
+### Option 2: CLI (Best for Automation & CI/CD)
+
+**Best for:** Scripting, CI/CD pipelines, batch processing, programmatic usage
+
+The CLI provides three installation methods:
+
+<details>
+<summary><b>Click to expand CLI installation options</b></summary>
+
+#### Using uv (Recommended for Development)
+
+This project uses [uv](https://github.com/astral-sh/uv) for fast, reliable Python package management.
+
+**For basic usage (compiling dashboards):**
+
+```bash
+uv sync
+```
+
+#### Using Docker
+
+Run the compiler in a container without installing Python or dependencies:
+
+```bash
+# Pull the pre-built image
+docker pull ghcr.io/strawgate/kb-yaml-to-lens/kb-dashboard-compiler:latest
+
+# Or build locally (from repo root)
+make cli docker-build
+```
+
+#### Standalone Binary
+
+Download a platform-specific binary from the [releases page](https://github.com/strawgate/kb-yaml-to-lens/releases):
+
+- Linux (x64): `kb-dashboard-linux-x64`
+- macOS (Intel): `kb-dashboard-darwin-x64`
+- macOS (Apple Silicon): `kb-dashboard-darwin-arm64`
+- Windows (x64): `kb-dashboard-windows-x64.exe`
+
+No Python installation required!
+
+</details>
+
+#### Compile Your First Dashboard (CLI)
+
+1. Create a YAML dashboard file in `inputs/` directory:
+
+```yaml
+dashboards:
+- name: My First Dashboard
+  description: A simple dashboard with markdown
+  panels:
+    - title: Welcome
+      grid: { x: 0, y: 0, w: 24, h: 15 }  # Position and size on 48-column grid
+      markdown:
+        content: |
+          # Welcome to Kibana!
+
+          This is my first dashboard compiled from YAML.
+```
+
+2. Compile to NDJSON:
+
+If using uv: `uv run kb-dashboard compile --input-dir inputs --output-dir output`
+
+If using Docker:
+```bash
+docker run --rm -v $(pwd)/inputs:/inputs -v $(pwd)/output:/output \
+  ghcr.io/strawgate/kb-yaml-to-lens/kb-dashboard-compiler:latest \
+  compile --input-dir inputs --output-dir output
+```
+
+If using standalone binary: `./kb-dashboard-<platform> compile --input-dir inputs --output-dir output`
+
+3. (Optional) Upload directly to Kibana:
+
+Add `--upload --kibana-url http://localhost:5601 --kibana-username elastic --kibana-password changeme` to the compile command above.
+
+The `--upload` flag will automatically open your dashboard in the browser upon successful upload.
+
+**Learn more:** [CLI Documentation](https://strawgate.github.io/kb-yaml-to-lens/CLI)
+
+## Documentation
+
+### Getting Started
+- **[VS Code Extension Guide](https://strawgate.github.io/kb-yaml-to-lens/vscode-extension)** - Visual dashboard development (recommended for beginners)
+- **[CLI Reference](https://strawgate.github.io/kb-yaml-to-lens/CLI)** - Command-line compilation and automation
+- **[Complete Examples](https://strawgate.github.io/kb-yaml-to-lens/examples/)** - Real-world dashboard examples you can copy
+
+### Deep Dive
+- **[Full Documentation Site](https://strawgate.github.io/kb-yaml-to-lens/)** - Complete user guide and API reference
+- **[Programmatic Usage Guide](https://strawgate.github.io/kb-yaml-to-lens/programmatic-usage)** - Create dashboards entirely in Python code
+- **[Architecture](https://strawgate.github.io/kb-yaml-to-lens/architecture)** - Technical design and data flow overview
+- **[Contributing Guide](../CONTRIBUTING.md)** - How to contribute and add new capabilities
+
+## License
+
+MIT
+
+## Support
+
+For issues and feature requests, please refer to the repository's issue tracker.

kb_dashboard_cli-0.2.0/pyproject.toml

@@ -0,0 +1,229 @@
+[project]
+name = "kb-dashboard-cli"
+version = "0.2.0"
+description = "CLI, LSP, and future MCP server for kb-yaml-to-lens dashboard compiler"
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Code Generators",
+]
+dependencies = [
+    "kb-dashboard-core",
+    "kb-dashboard-tools",
+    "click>=8.3",
+    "rich-click>=1.9.0",
+    "elasticsearch>=8.16.2",
+    "pygls>=2.0.0",
+    "lsprotocol>=2024.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0",
+    "pytest-cov>=6.0",
+    "deepdiff>=8.4.2",
+    "pytest-asyncio>=1.3",
+    "inline-snapshot>=0.31.1",
+    "dirty-equals>=0.8.0",
+    "pytest-examples>=0.0.18",
+    "pydantic2zod @ git+https://github.com/argyle-engineering/pydantic2zod@0.1.1",
+]
+
+[project.scripts]
+kb-dashboard = "dashboard_compiler.cli:cli"
+
+[tool.pytest.ini_options]
+asyncio_default_fixture_loop_scope = "function"
+asyncio_mode = "auto"
+addopts = "-vv"
+
+[tool.inline-snapshot]
+format-command = "ruff format"
+
+[build-system]
+requires = ["uv_build>=0.8.2,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "dashboard_compiler"
+
+[tool.uv.sources]
+kb-dashboard-core = { workspace = true }
+kb-dashboard-tools = { workspace = true }
+
+[tool.ruff]
+line-length = 140
+# Assume Python 3.12
+target-version = "py312"
+# Add commonly ignored directories
+extend-exclude = [
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "reference",
+    "**/*.old.py",
+]
+
+[tool.ruff.lint]
+
+# When using extend-select, a rule like PLR will enable PLR* rules like PLR0###.
+extend-select = [
+    "A", "ARG", "B", "C4", "COM", "DTZ", "E", "EM", "F", "FURB", "I",
+    "LOG", "N", "PERF", "PIE", "PLR", "PLW", "PT", "PTH", "Q", "RET",
+    "RSE", "RUF", "S", "SIM", "TC", "TID", "TRY", "UP", "W",
+    "D",  # Add docstring checks since kb-yaml-to-lens uses them
+    # Additional quality and safety rules:
+    "ANN",  # flake8-annotations - Type annotations
+    "PLE",  # Pylint errors - Serious bug detection
+    "T10",  # flake8-debugger - Prevent debugger statements
+    "ISC",  # flake8-implicit-str-concat - Prevent string concat bugs
+    "FA",   # flake8-future-annotations - Modern type hints (PEP 563)
+    "PGH",  # pygrep-hooks - Additional code quality checks
+    "INP",  # flake8-no-pep420 - Explicit namespace packages
+]
+ignore = [
+    "COM812",  # Conflicts with formatter
+    "D203",    # incorrect-blank-line-before-class
+    "D213",    # multi-line-summary-second-line
+    "D413",    # multi-line-summary-second-line
+    "D100",    # Ignore missing docstrings for modules
+    "A002",    # Allow shadowing builtin names (e.g., 'filter')
+    "ANN401",  # We use Pyright for Any checking
+]
+
+# Per-file rule ignores
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]    # Ignore unused imports in __init__.py files
+"tests/**/*.py" = [
+    "S101", # Allow assert usage in tests
+    "PLR2004", # Allow magic values in test assertions
+    "INP001", # Tests are not meant to be imported as packages
+]
+"src/dashboard_compiler/**/view.py" = [
+    "N815", # Ignore casing requirements for view models
+    "N803",  # Ignore lowercase arguments in view models
+    "D101", # Ignore missing docstrings in view models
+    "ANN202", # Ignore missing return type for private serializer methods
+    "ERA001", # Allow commented JSON structure documentation
+]
+"src/dashboard_compiler/lsp/grid_*.py" = [
+    "PLR2004", # Allow magic numbers (CLI arg counts)
+    "PLR0911", # Allow many return statements in grid_updater
+    "PLR0912", # Allow many branches in grid_updater
+    "PLR0915", # Allow many statements in grid_updater
+]
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.isort]
+known-first-party = ["dashboard_compiler"]
+section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]
+
+[tool.ruff.lint.flake8-quotes]
+docstring-quotes = "double"
+inline-quotes = "single"
+
+[tool.ruff.lint.pep8-naming]
+classmethod-decorators = ["classmethod", "pydantic.validator"]
+
+[tool.coverage.run]
+source = ["src/dashboard_compiler"]
+branch = true
+relative_files = true
+omit = [
+    "*/tests/*",
+    "*/test_*.py",
+    "*/__pycache__/*",
+    "*/packages/vscode-extension/*",
+]
+
+[tool.coverage.report]
+precision = 2
+show_missing = true
+skip_covered = false
+skip_empty = true
+# Enforce minimum coverage threshold (fails if below this percentage)
+fail_under = 80
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+
+[tool.coverage.html]
+directory = "htmlcov"
+
+[tool.coverage.json]
+# Do not fail JSON export based on coverage threshold
+# (threshold enforcement happens in [tool.coverage.report] for make test-coverage)
+output = "coverage.json"
+show_contexts = false
+
+[tool.basedpyright]
+pythonVersion = "3.12"
+typeCheckingMode = "recommended"
+reportImportCycles = "error"
+reportExplicitAny = false
+reportIncompatibleVariableOverride = false
+include = ["src/dashboard_compiler", "tests"]
+exclude = [
+    "**/.venv/**",
+    "**/output/**",
+    "**/*.old.py",
+]
+[[tool.basedpyright.executionEnvironments]]
+root = "tests"
+# Tests use many libraries and test patterns that trigger type warnings.
+# The volume of warnings makes inline ignores impractical for test code.
+reportMissingTypeStubs = false
+reportUnknownParameterType = false
+reportUnknownArgumentType = false
+reportUnknownVariableType = false
+reportAny = false
+reportArgumentType = false
+reportCallIssue = false
+reportMissingImports = false
+reportUninitializedInstanceVariable = false
+reportUnusedCallResult = false
+reportImplicitOverride = false
+reportPrivateUsage = false
+reportUnannotatedClassAttribute = false
+reportUntypedNamedTuple = false
+
+[[tool.basedpyright.executionEnvironments]]
+root = "src/dashboard_compiler/panels/charts/lens/metrics/formula_parser.py"
+# Formula parser uses TatSu which lacks type stubs and returns untyped AST structures.
+# With 100+ type unknowns, per-line ignores would severely harm readability.
+reportMissingTypeStubs = false
+reportAny = false
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+reportUnknownArgumentType = false
+
+[[tool.basedpyright.executionEnvironments]]
+root = "src/dashboard_compiler/yaml_roundtrip.py"
+# ruamel.yaml lacks type stubs and returns dynamic types from load/dump operations.
+reportAny = false
+reportUnknownMemberType = false
+
+[[tool.basedpyright.executionEnvironments]]
+root = "src/dashboard_compiler"

kb_dashboard_cli-0.2.0/src/dashboard_compiler/__init__.py

@@ -0,0 +1,23 @@
+"""Dashboard CLI Package - CLI, LSP, and future MCP server for kb-yaml-to-lens."""
+
+from beartype import BeartypeConf
+from beartype.claw import beartype_this_package
+from kb_dashboard_core.dashboard_compiler import dump, load, render
+from kb_dashboard_tools import KibanaClient
+
+# Enable strict BearType checking:
+# - warning_cls_on_decorator_exception=None: Raises fatal exceptions instead of warnings
+# - claw_is_pep526=True: Type-check annotated variable assignments (default, explicit for clarity)
+beartype_this_package(
+    conf=BeartypeConf(
+        warning_cls_on_decorator_exception=None,
+        claw_is_pep526=True,
+    )
+)
+
+__all__ = [
+    'KibanaClient',
+    'dump',
+    'load',
+    'render',
+]