ploston-cli 1.0.0__tar.gz

ploston_cli-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run ruff check
+        run: uv run ruff check src/ tests/
+
+      - name: Run ruff format check
+        run: uv run ruff format --check src/ tests/
+
+  unit-tests:
+    name: Unit Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run unit tests
+        run: |
+          uv run pytest tests/unit/ -v \
+            --cov=ploston_cli \
+            --cov-report=xml \
+            --cov-report=html \
+            --junitxml=junit-unit-${{ matrix.python-version }}.xml
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: test-results-${{ matrix.python-version }}
+          path: junit-unit-${{ matrix.python-version }}.xml
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        if: matrix.python-version == '3.12'
+        with:
+          name: coverage-report
+          path: htmlcov/
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: [lint, unit-tests]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Check package installable
+        run: |
+          uv venv .test-venv
+          uv pip install --python .test-venv dist/*.whl
+          uv run --python .test-venv python -c "import ploston_cli; print(ploston_cli.__name__)"
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+

ploston_cli-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,79 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      test_pypi:
+        description: 'Publish to Test PyPI instead of PyPI'
+        required: false
+        default: 'false'
+        type: boolean
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.test_pypi == 'false')
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ploston-cli
+    permissions:
+      id-token: write  # OIDC publishing
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-to-test-pypi:
+    name: Publish to Test PyPI
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.test_pypi == 'true'
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: test-pypi
+      url: https://test.pypi.org/p/ploston-cli
+    permissions:
+      id-token: write  # OIDC publishing
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+

ploston_cli-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+
+# Coverage
+.coverage
+coverage.xml
+htmlcov/
+

ploston_cli-1.0.0/Makefile

@@ -0,0 +1,128 @@
+# Ploston CLI
+# ===========
+# Development commands for local testing and PyPI publishing
+#
+# Quick start:
+#   make install    # Install dependencies
+#   make test       # Run tests
+#   make build      # Build package
+
+# Configuration
+PYTHON = uv run python
+PYTEST = uv run pytest
+PACKAGE_NAME = ploston-cli
+
+# Colors
+CYAN := \033[36m
+GREEN := \033[32m
+YELLOW := \033[33m
+RED := \033[31m
+RESET := \033[0m
+
+.PHONY: help install test lint format build publish-test publish clean
+
+# =============================================================================
+# HELP
+# =============================================================================
+
+help:
+	@echo ""
+	@echo "$(CYAN)Ploston CLI$(RESET)"
+	@echo "==========="
+	@echo ""
+	@echo "$(GREEN)Development:$(RESET)"
+	@echo "  make install      Install dependencies with uv"
+	@echo "  make test         Run all tests"
+	@echo "  make test-unit    Run unit tests only"
+	@echo "  make lint         Run ruff linter"
+	@echo "  make format       Format code with ruff"
+	@echo "  make check        Run lint + format check + tests"
+	@echo ""
+	@echo "$(GREEN)Build & Publish:$(RESET)"
+	@echo "  make build        Build package (sdist + wheel)"
+	@echo "  make publish-test Publish to TestPyPI"
+	@echo "  make publish      Publish to PyPI"
+	@echo ""
+	@echo "$(GREEN)Maintenance:$(RESET)"
+	@echo "  make clean        Remove build artifacts"
+	@echo ""
+
+# =============================================================================
+# DEVELOPMENT
+# =============================================================================
+
+## Install dependencies
+install:
+	@echo "$(CYAN)Installing dependencies...$(RESET)"
+	uv sync --all-extras
+	@echo "$(GREEN)Done!$(RESET)"
+
+## Run all tests
+test:
+	@echo "$(CYAN)Running all tests...$(RESET)"
+	$(PYTEST) tests/ -v
+
+## Run unit tests only
+test-unit:
+	@echo "$(CYAN)Running unit tests...$(RESET)"
+	$(PYTEST) tests/unit/ -v
+
+## Run tests with coverage
+test-cov:
+	@echo "$(CYAN)Running tests with coverage...$(RESET)"
+	$(PYTEST) tests/ -v --cov=ploston_cli --cov-report=html --cov-report=term
+
+## Run linter
+lint:
+	@echo "$(CYAN)Running linter...$(RESET)"
+	uv run ruff check src/ tests/
+	uv run ruff format --check src/ tests/
+
+## Format code
+format:
+	@echo "$(CYAN)Formatting code...$(RESET)"
+	uv run ruff format src/ tests/
+	uv run ruff check --fix src/ tests/
+
+## Run all checks
+check: lint test
+	@echo "$(GREEN)All checks passed!$(RESET)"
+
+# =============================================================================
+# BUILD & PUBLISH
+# =============================================================================
+
+## Build package
+build: clean
+	@echo "$(CYAN)Building package...$(RESET)"
+	uv build
+	@echo "$(GREEN)Build complete!$(RESET)"
+	@ls -la dist/
+
+## Publish to TestPyPI
+publish-test: build
+	@echo "$(CYAN)Publishing to TestPyPI...$(RESET)"
+	uv publish --publish-url https://test.pypi.org/legacy/
+	@echo "$(GREEN)Published to TestPyPI!$(RESET)"
+	@echo "Install with: pip install -i https://test.pypi.org/simple/ $(PACKAGE_NAME)"
+
+## Publish to PyPI
+publish: build
+	@echo "$(CYAN)Publishing to PyPI...$(RESET)"
+	uv publish
+	@echo "$(GREEN)Published to PyPI!$(RESET)"
+	@echo "Install with: pip install $(PACKAGE_NAME)"
+
+# =============================================================================
+# MAINTENANCE
+# =============================================================================
+
+## Remove build artifacts
+clean:
+	@echo "$(CYAN)Cleaning build artifacts...$(RESET)"
+	rm -rf build/ dist/ *.egg-info/
+	rm -rf .pytest_cache/ .mypy_cache/ .ruff_cache/
+	rm -rf htmlcov/ .coverage
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	@echo "$(GREEN)Clean!$(RESET)"
+

ploston_cli-1.0.0/PKG-INFO

@@ -0,0 +1,339 @@
+Metadata-Version: 2.4
+Name: ploston-cli
+Version: 1.0.0
+Summary: CLI for Ploston - Deterministic Agent Execution Layer
+Project-URL: Homepage, https://github.com/ostanlabs/ploston-cli
+Project-URL: Documentation, https://ostanlabs.netlify.app
+Project-URL: Repository, https://github.com/ostanlabs/ploston-cli
+Author-email: Ostan Labs <hello@ostanlabs.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: ploston-core<2.0.0,>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Ploston CLI
+
+Command-line interface for Ploston - Deterministic Agent Execution Layer
+
+## Overview
+
+The Ploston CLI provides a powerful command-line interface for interacting with Ploston servers.
+It works with both the open-source community tier and enterprise tier.
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install ploston-cli
+```
+
+### From Source
+
+```bash
+git clone https://github.com/ostanlabs/ploston-cli.git
+cd ploston-cli
+make install
+```
+
+### Verify Installation
+
+```bash
+ploston version
+```
+
+## Quick Start
+
+```bash
+# Start the MCP server
+ploston serve
+
+# List available workflows
+ploston workflows list
+
+# Run a workflow
+ploston run my-workflow -i key=value
+
+# Validate a workflow file
+ploston validate workflow.yaml
+```
+
+## Commands
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-c, --config PATH` | Config file path |
+| `-v, --verbose` | Increase verbosity (can be repeated) |
+| `-q, --quiet` | Suppress output |
+| `--json` | Output as JSON |
+
+### `ploston serve`
+
+Start the MCP server.
+
+```bash
+# Start with default settings (stdio transport)
+ploston serve
+
+# Start with HTTP transport
+ploston serve --transport http --port 8080
+
+# Start with REST API enabled
+ploston serve --transport http --with-api --api-docs
+
+# Force configuration mode
+ploston serve --mode configuration
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--transport` | `stdio` | Transport type (`stdio` or `http`) |
+| `--host` | `0.0.0.0` | HTTP host |
+| `--port` | `8080` | HTTP port |
+| `--no-watch` | `false` | Disable config hot-reload |
+| `--mode` | auto | Force mode (`configuration` or `running`) |
+| `--with-api` | `false` | Enable REST API (HTTP only) |
+| `--api-prefix` | `/api/v1` | REST API URL prefix |
+| `--api-docs` | `false` | Enable OpenAPI docs at /docs |
+
+### `ploston run`
+
+Execute a workflow.
+
+```bash
+# Run with inline inputs
+ploston run my-workflow -i name=John -i age=30
+
+# Run with input file
+ploston run my-workflow --input-file inputs.yaml
+
+# Run with timeout
+ploston run my-workflow -t 60
+
+# Get JSON output
+ploston --json run my-workflow
+```
+
+| Option | Description |
+|--------|-------------|
+| `-i, --input KEY=VALUE` | Input parameter (can be repeated) |
+| `--input-file PATH` | YAML/JSON file with inputs |
+| `-t, --timeout SECONDS` | Execution timeout |
+
+### `ploston validate`
+
+Validate a workflow YAML file.
+
+```bash
+# Basic validation
+ploston validate workflow.yaml
+
+# Strict mode (warnings as errors)
+ploston validate --strict workflow.yaml
+
+# Check that tools exist (requires MCP connection)
+ploston validate --check-tools workflow.yaml
+```
+
+| Option | Description |
+|--------|-------------|
+| `--strict` | Treat warnings as errors |
+| `--check-tools` | Verify tools exist |
+
+### `ploston workflows`
+
+Manage workflows.
+
+```bash
+# List all workflows
+ploston workflows list
+
+# Show workflow details
+ploston workflows show my-workflow
+
+# JSON output
+ploston --json workflows list
+```
+
+### `ploston tools`
+
+Manage tools.
+
+```bash
+# List all tools
+ploston tools list
+
+# Filter by source
+ploston tools list --source mcp
+
+# Filter by server
+ploston tools list --server native-tools
+
+# Show tool details
+ploston tools show read_file
+
+# Refresh tool schemas
+ploston tools refresh
+ploston tools refresh --server native-tools
+```
+
+| Option | Description |
+|--------|-------------|
+| `--source` | Filter by source (`mcp` or `system`) |
+| `--server` | Filter by MCP server name |
+| `--status` | Filter by status (`available` or `unavailable`) |
+
+### `ploston config`
+
+Manage configuration.
+
+```bash
+# Show full config
+ploston config show
+
+# Show specific section
+ploston config show --section mcp
+
+# JSON output
+ploston --json config show
+```
+
+Valid sections: `server`, `mcp`, `tools`, `workflows`, `execution`, `python_exec`, `logging`, `plugins`, `security`, `telemetry`
+
+### `ploston api`
+
+Start standalone REST API server.
+
+```bash
+# Start API server
+ploston api --port 8080
+
+# With authentication required
+ploston api --require-auth
+
+# With rate limiting
+ploston api --rate-limit 100
+
+# With SQLite execution store
+ploston api --db ./executions.db
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--host` | `0.0.0.0` | Host to bind to |
+| `--port` | `8080` | Port to bind to |
+| `--prefix` | `/api/v1` | API prefix |
+| `--no-docs` | `false` | Disable OpenAPI docs |
+| `--require-auth` | `false` | Require API key |
+| `--rate-limit` | `0` | Requests per minute (0=disabled) |
+| `--db` | - | SQLite database path |
+
+### `ploston version`
+
+Show version information.
+
+```bash
+ploston version
+```
+
+## Configuration
+
+The CLI looks for configuration in the following order:
+
+1. Path specified with `-c/--config`
+2. `./ael-config.yaml` (current directory)
+3. `~/.ael/config.yaml` (home directory)
+
+If no config is found, the server starts in **configuration mode** where you can use MCP tools to set up the configuration.
+
+### Example Config
+
+```yaml
+# ael-config.yaml
+server:
+  host: 0.0.0.0
+  port: 8080
+
+mcp:
+  servers:
+    native-tools:
+      command: python
+      args: ["-m", "native_tools"]
+
+workflows:
+  paths:
+    - ./workflows/
+
+logging:
+  level: INFO
+```
+
+## JSON Output
+
+All commands support `--json` for machine-readable output:
+
+```bash
+# List workflows as JSON
+ploston --json workflows list
+
+# Run workflow with JSON output
+ploston --json run my-workflow -i key=value
+
+# Validate with JSON output
+ploston --json validate workflow.yaml
+```
+
+## Development
+
+### Prerequisites
+
+- Python 3.12+
+- [uv](https://github.com/astral-sh/uv) package manager
+
+### Setup
+
+```bash
+make install
+```
+
+### Commands
+
+```bash
+make help       # Show all commands
+make test       # Run all tests
+make test-unit  # Run unit tests only
+make lint       # Run linter
+make format     # Format code
+make check      # Run lint + tests
+make build      # Build package
+```
+
+## Features
+
+- **HTTP-only client**: No server dependencies, works with any Ploston server
+- **Tier detection**: Automatically detects community vs enterprise features
+- **Rich output**: Beautiful terminal output with colors and formatting
+- **JSON mode**: Machine-readable output for scripting
+- **Config hot-reload**: Automatically reloads config changes
+- **Dual-mode server**: Run MCP and REST API simultaneously
+
+## License
+
+Apache-2.0