kctl-vendure 0.6.2__tar.gz

kctl_vendure-0.6.2/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_vendure-0.6.2/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-vendure
+Version: 0.6.2
+Summary: Kodemeio Vendure CLI — manage Vendure e-commerce via GraphQL Admin API
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.7.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'

kctl_vendure-0.6.2/README.md

@@ -0,0 +1,120 @@
+# kctl-vendure
+
+Kodemeio Vendure CLI — manage e-commerce via GraphQL Admin API.
+
+## Installation
+
+```bash
+# From workspace (development)
+uv tool install --editable packages/kctl-vendure
+
+# From PyPI
+uv tool install kctl-vendure
+```
+
+## Quick Start
+
+```bash
+# Initialize configuration
+kctl-vendure config init
+
+# Test API connectivity
+kctl-vendure config test
+
+# List products
+kctl-vendure products list
+
+# List recent orders
+kctl-vendure orders list --take 20
+
+# View customer details
+kctl-vendure customers show cust-123
+
+# Check payment status
+kctl-vendure payments list --order 456
+```
+
+## Command Groups
+
+| Group | Commands | Description |
+|-------|----------|-------------|
+| `config` | init, add, use, show, set, remove, profiles, current, test, migrate | Manage profiles and credentials |
+| `products` | list, show, create, update, delete, variants | Product catalog management |
+| `orders` | list, show, update, cancel, refund, fulfill | Order lifecycle management |
+| `customers` | list, show, create, update, delete | Customer account management |
+| `assets` | list, show, upload, delete | Digital asset management |
+| `payments` | list, show, settle, cancel | Payment processing operations |
+| `doctor` | check | Diagnostic checks (GraphQL connectivity, auth, config) |
+
+## Global Options
+
+All commands accept these options:
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | Output as JSON |
+| `--format` | `-f` | Output format: `pretty`, `json`, `csv`, `yaml` |
+| `--quiet` | `-q` | Suppress info messages |
+| `--no-header` | | Omit header row in table/CSV output |
+| `--profile` | `-p` | Config profile name |
+| `--version` | `-V` | Show version and exit |
+
+## Configuration
+
+Config is stored in `~/.config/kodemeio/config.yaml` under the `vendure` key.
+
+```bash
+# Create a new profile
+kctl-vendure config init
+
+# Add a named profile
+kctl-vendure config add --profile prod
+
+# Switch active profile
+kctl-vendure config use prod
+
+# Show current config (secrets masked)
+kctl-vendure config show
+
+# Test connectivity
+kctl-vendure config test
+```
+
+### Config Keys
+
+| Key | Description |
+|-----|-------------|
+| `url` | Vendure Admin API URL (e.g. `https://shop.example.com/admin-api`) |
+| `admin_username` | Admin user login (email) |
+| `admin_password` | Admin user password |
+
+### Profile Example
+
+```yaml
+profiles:
+  kodemeio:
+    vendure:
+      url: https://shop.kodeme.io/admin-api
+      admin_username: admin@kodeme.io
+      admin_password: ${VENDURE_ADMIN_PASSWORD}
+```
+
+## Common Workflows
+
+```bash
+# Fulfill an order
+kctl-vendure orders fulfill 789 --tracking "TRACK123"
+
+# Export orders as CSV
+kctl-vendure orders list --format csv > orders.csv
+```
+
+## Development
+
+```bash
+cd packages/kctl-vendure
+uv sync --all-extras
+uv run pytest tests/ -v
+uv run mypy src/
+uv run ruff check src/
+```

kctl_vendure-0.6.2/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-vendure"
+version = "0.6.2"
+description = "Kodemeio Vendure CLI — manage Vendure e-commerce via GraphQL Admin API"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.7.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-vendure = "kctl_vendure.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_vendure"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_vendure-0.6.2/skills/vendure-admin/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: vendure-admin
+description: >
+  Vendure e-commerce management via kctl-vendure CLI.
+  MUST use for ANY kctl-vendure operation.
+  Triggers on: "vendure, e-commerce, ecommerce, products, orders, customers, shop, payments".
+---
+
+# kctl-vendure
+
+Kodemeio Vendure CLI - manage your Vendure e-commerce instance (products, orders, customers, assets, payments).
+
+## Installation
+
+```bash
+uv tool install kctl-vendure
+```
+
+## Global Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | JSON output (shortcut for --format json) |
+| `--quiet` | `-q` | Suppress info messages |
+| `--format` | `-f` | Output format: pretty/json/csv/yaml |
+| `--no-header` | | Omit headers in CSV output |
+| `--debug` | | Enable debug logging |
+| `--profile` | `-p` | Config profile name |
+| `--url` | | API URL override |
+| `--username` | `-u` | Admin username override |
+| `--password` | | Admin password override |
+| `--version` | `-V` | Show version |
+
+## Commands
+
+### config
+- `kctl-vendure config init` — Initialize CLI configuration
+- `kctl-vendure config show` — Show configuration (passwords masked)
+- `kctl-vendure config test` — Test API connection
+
+### products
+- `kctl-vendure products list` — List products
+- `kctl-vendure products get` — Get a single product with variants
+- `kctl-vendure products stock` — Update stock level for a product variant
+
+### orders
+- `kctl-vendure orders list` — List orders
+- `kctl-vendure orders get` — Get a single order with line items
+- `kctl-vendure orders fulfill` — Add fulfillment to an order
+- `kctl-vendure orders cancel` — Cancel an order
+
+### customers
+- `kctl-vendure customers list` — List customers
+- `kctl-vendure customers get` — Get a single customer with order history
+
+### assets
+- `kctl-vendure assets list` — List assets
+- `kctl-vendure assets delete` — Delete an asset
+
+### payments
+- `kctl-vendure payments list` — List payments for an order
+- `kctl-vendure payments status` — List available payment methods and their status
+
+### doctor
+- `kctl-vendure doctor` — Run diagnostic checks
+
+## Configuration
+
+Service key: `vendure` in `~/.config/kodemeio/config.yaml`
+
+```yaml
+profiles:
+  terakidz:
+    vendure:
+      url: https://shop-api.terakidz.com
+      username: admin
+      password: <password>
+```

kctl_vendure-0.6.2/src/kctl_vendure/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-vendure: Kodemeio Vendure e-commerce CLI."""
+
+__version__ = "0.6.2"

kctl_vendure-0.6.2/src/kctl_vendure/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m kctl_vendure."""
+
+from kctl_vendure.cli import _run
+
+_run()

kctl_vendure-0.6.2/src/kctl_vendure/cli.py

@@ -0,0 +1,101 @@
+"""Main CLI entry point for kctl-vendure."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from kctl_lib import KctlError, handle_cli_error
+
+from kctl_vendure import __version__
+from kctl_vendure.commands.assets import app as assets_app
+from kctl_vendure.commands.config_cmd import app as config_app
+from kctl_vendure.commands.customers import app as customers_app
+from kctl_vendure.commands.doctor import app as doctor_app
+from kctl_vendure.commands.orders import app as orders_app
+from kctl_vendure.commands.payments import app as payments_app
+from kctl_vendure.commands.products import app as products_app
+from kctl_vendure.core.callbacks import AppContext
+from kctl_lib.self_update import notify_if_outdated
+from kctl_lib.tui import add_tui_command
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-vendure {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-vendure",
+    help="Kodemeio Vendure CLI - manage your Vendure e-commerce instance.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON (shortcut for --format json)")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    output_format: Annotated[
+        str, typer.Option("--format", "-f", help="Output format: pretty, json, csv, yaml")
+    ] = "pretty",
+    no_header: Annotated[bool, typer.Option("--no-header", help="Omit headers in CSV output")] = False,
+    debug: Annotated[bool, typer.Option("--debug", help="Enable debug logging")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    url: Annotated[str | None, typer.Option("--url", help="API URL override")] = None,
+    username: Annotated[str | None, typer.Option("--username", "-u", help="Admin username override")] = None,
+    password: Annotated[str | None, typer.Option("--password", help="Admin password override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio Vendure e-commerce CLI."""
+    import os
+
+    if debug:
+        os.environ["KCTL_DEBUG"] = "1"
+
+    effective_format = "json" if json_output else output_format
+
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output or effective_format == "json",
+        quiet=quiet,
+        format=effective_format,
+        no_header=no_header,
+        debug=debug,
+        profile=profile,
+        url_override=url,
+        username_override=username,
+        password_override=password,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-vendure", __version__)
+
+
+# ---------------------------------------------------------------------------
+# Command groups
+# ---------------------------------------------------------------------------
+app.add_typer(config_app, name="config")
+app.add_typer(products_app, name="products")
+app.add_typer(orders_app, name="orders")
+app.add_typer(customers_app, name="customers")
+app.add_typer(assets_app, name="assets")
+app.add_typer(payments_app, name="payments")
+app.add_typer(doctor_app, name="doctor")
+add_tui_command(app, service_key="vendure", version=__version__)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_vendure-0.6.2/src/kctl_vendure/commands/assets.py

@@ -0,0 +1,90 @@
+"""Asset management commands for Vendure e-commerce."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_vendure.core.callbacks import AppContext
+
+app = typer.Typer(help="Manage Vendure assets.")
+
+# ---------------------------------------------------------------------------
+# GraphQL Operations
+# ---------------------------------------------------------------------------
+
+ASSETS_LIST_QUERY = """
+query GetAssets($options: AssetListOptions) {
+    assets(options: $options) {
+        items {
+            id
+            name
+            type
+            fileSize
+            mimeType
+            source
+            preview
+        }
+        totalItems
+    }
+}
+"""
+
+DELETE_ASSET_MUTATION = """
+mutation DeleteAsset($input: DeleteAssetInput!) {
+    deleteAsset(input: $input) {
+        result
+        message
+    }
+}
+"""
+
+
+@app.command("list")
+def list_cmd(
+    ctx: typer.Context,
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Number of assets to return")] = 10,
+    skip: Annotated[int, typer.Option("--skip", help="Number of assets to skip")] = 0,
+) -> None:
+    """List assets."""
+    c: AppContext = ctx.obj
+    out = c.output
+    variables = {"options": {"take": limit, "skip": skip}}
+    data = c.client.query(ASSETS_LIST_QUERY, variables)
+    assets_data = data.get("assets", {})
+    items = assets_data.get("items", [])
+    total = assets_data.get("totalItems", 0)
+
+    if c.json_mode:
+        out.raw_json({"items": items, "totalItems": total})
+    else:
+        out.info(f"Assets ({total} total)")
+        out.table(items, columns=["id", "name", "type", "fileSize", "mimeType"], title="Assets")
+
+
+@app.command()
+def delete(
+    ctx: typer.Context,
+    asset_id: Annotated[str, typer.Argument(help="Asset ID")],
+    force: Annotated[bool, typer.Option("--force", "-f", help="Skip confirmation and force delete")] = False,
+) -> None:
+    """Delete an asset."""
+    c: AppContext = ctx.obj
+    out = c.output
+
+    if not force:
+        typer.confirm(f"Delete asset {asset_id}?", abort=True)
+
+    variables = {"input": {"assetId": asset_id, "force": force}}
+    data = c.client.mutate(DELETE_ASSET_MUTATION, variables)
+    result = data.get("deleteAsset", {})
+
+    if c.json_mode:
+        out.raw_json(result)
+    else:
+        if result.get("result") == "DELETED":
+            out.success(f"Asset {asset_id} deleted")
+        else:
+            out.error(f"Delete failed: {result.get('message', 'Unknown error')}")
+            raise typer.Exit(1)

kctl_vendure-0.6.2/src/kctl_vendure/commands/config_cmd.py

@@ -0,0 +1,108 @@
+"""Configuration management commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_vendure.core.callbacks import AppContext
+from kctl_vendure.core.config import (
+    CONFIG_FILE,
+    SERVICE_KEY,
+    ServiceConfig,
+    get_all_services_in_profile,
+    get_default_profile,
+    get_profile_names,
+    resolve_active_profile_name,
+    set_default_profile,
+    set_service_config,
+)
+
+app = typer.Typer(help="Manage CLI configuration and profiles.")
+
+
+def _mask(val: str) -> str:
+    if not val:
+        return "[dim]not set[/dim]"
+    return f"{val[:4]}{'*' * max(0, len(val) - 8)}{val[-4:]}" if len(val) > 10 else "****"
+
+
+@app.command()
+def init(
+    ctx: typer.Context,
+    url: Annotated[str | None, typer.Option("--url")] = None,
+    username: Annotated[str | None, typer.Option("--username", "-u")] = None,
+    password: Annotated[str | None, typer.Option("--password")] = None,
+    name: Annotated[str | None, typer.Option("--name", "-n")] = None,
+) -> None:
+    """Initialize CLI configuration."""
+    c: AppContext = ctx.obj
+    out = c.output
+    profile_name = name or typer.prompt("Profile name", default="kodemeio")
+    api_url = url or typer.prompt("Vendure URL (e.g. https://shop.example.com)")
+    admin_user = username or typer.prompt("Admin username", default="superadmin")
+    admin_pass = password or typer.prompt("Admin password", hide_input=True)
+
+    svc = ServiceConfig(url=api_url, admin_username=admin_user, admin_password=admin_pass)
+    set_service_config(profile_name, svc)
+    if len(get_profile_names()) <= 1:
+        set_default_profile(profile_name)
+    out.success(f"Configuration saved to {CONFIG_FILE}")
+    out.kv("Profile", profile_name)
+    out.kv("URL", api_url)
+    out.kv("Username", admin_user)
+    out.kv("Password", _mask(admin_pass))
+
+
+@app.command()
+def show(ctx: typer.Context) -> None:
+    """Show configuration (passwords masked)."""
+    c: AppContext = ctx.obj
+    out = c.output
+    default = get_default_profile()
+    sections = [
+        (
+            "General",
+            [
+                ("Config file", str(CONFIG_FILE)),
+                ("Default profile", default),
+                ("Service key", SERVICE_KEY),
+            ],
+        )
+    ]
+    for pname in get_profile_names():
+        marker = " [green](default)[/green]" if pname == default else ""
+        services = get_all_services_in_profile(pname)
+        kvs = []
+        for svc_name, svc_data in services.items():
+            if not isinstance(svc_data, dict):
+                continue
+            indicator = "[green]●[/green]" if svc_name == SERVICE_KEY else "[dim]○[/dim]"
+            kvs.append(
+                (
+                    f"{indicator} {svc_name}",
+                    f"{svc_data.get('url', '')}  user: {svc_data.get('admin_username', '')}  pass: {_mask(svc_data.get('admin_password', ''))}",
+                )
+            )
+        sections.append((f"Profile: {pname}{marker}", kvs or [("(empty)", "")]))
+    out.detail("Configuration", sections)
+
+
+@app.command()
+def test(ctx: typer.Context) -> None:
+    """Test API connection."""
+    c: AppContext = ctx.obj
+    out = c.output
+    active = resolve_active_profile_name(c.profile)
+    out.info(f"Testing profile '{active}' -> {SERVICE_KEY}")
+    try:
+        status = c.client.check_health()
+        if status == 200:
+            out.success("Connected to Vendure API")
+        else:
+            out.error(f"Connection failed: HTTP {status}")
+            raise typer.Exit(1)
+    except Exception as e:
+        out.error(f"Connection failed: {e}")
+        raise typer.Exit(1) from e