cliyard 0.3.2__tar.gz

cliyard-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cliyard-0.3.2/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: cliyard
+Version: 0.3.2
+Summary: YAML-driven CLI framework — turn any REST API into CLI commands
+Author-email: keta <dev@ketaops.cc>
+License: MIT
+Project-URL: Homepage, https://github.com/guolong123/cliyard
+Project-URL: Repository, https://github.com/guolong123/cliyard.git
+Keywords: cli,yaml,rest-api,codegen,click
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1.0
+Requires-Dist: pyyaml~=6.0
+Requires-Dist: requests~=2.31.0
+Requires-Dist: jinja2~=3.1
+Requires-Dist: rich>=13.7.0
+Requires-Dist: jsonpath-ng~=1.7.0
+Dynamic: license-file
+
+# cliyard
+
+**CLI + YAML + Yard** — a framework that generates CLI commands from YAML specs. Define your REST API in a few YAML files, and cliyard produces a fully-structured Click CLI with parameters, types, and auto-generated help. Originally inspired by [ketacli](https://gitee.com/xishuhq/ketacli)'s YAML-driven architecture, now generalized for any REST API.
+
+## Installation
+
+```bash
+pip install cliyard
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Explore the example spec
+cliyard --spec-dir examples/ketacli-repos/ repos list --help
+
+# Usage: repos list [OPTIONS]
+#   --page INTEGER        Page number
+#   --search TEXT         Search keyword
+#   --help                Show this message and exit.
+```
+
+## How It Works
+
+cliyard turns a directory of YAML files into CLI commands. One directory equals one API service. Each YAML file (except `_service.yaml`) becomes a resource group with subcommands for every defined method.
+
+```
+your-api/                          ┌─────────────────────────────────┐
+├── _service.yaml  ── service ──►  │  cliyard Engine                 │
+├── repos.yaml     ── resource ──► │                                 │
+├── users.yaml     ── resource ──► │  Loader ──► Builder ──► Click   │
+└── ...                            │    │            │           │    │
+                                   │    │     Auth Chain          │    │
+                                   │    ▼            ▼           ▼    │
+                                   │  YAML       Commands    CLI run  │
+                                   │  parsing    + params              │
+                                   └─────────────────────────────────┘
+```
+
+**Data flow** for a single invocation:
+
+```
+cliyard --spec-dir examples/ketacli-repos/ repos list --page 1
+
+    1. Loader reads _service.yaml + repos.yaml
+    2. Auth chain runs (env → login → inject token)
+    3. Builder generates Click commands from method specs
+    4. Params are typed (int, string, enum, bool) and validated
+    5. (Future) HTTP request is assembled and sent
+    6. (Future) Response is formatted with Rich tables
+```
+
+## Directory Structure
+
+Each service is a directory containing a `_service.yaml` for service-level config and one YAML file per resource:
+
+```
+ketacli-repos/
+├── _service.yaml      # Service config: name, server, auth
+└── repos.yaml         # Resource: repos (list, create, get, update, delete)
+```
+
+- `_service.yaml` defines the server URL, authentication chain, and global settings.
+- Resource files (`repos.yaml`, `users.yaml`, etc.) define the methods, parameters, and output format for each API resource.
+- Files prefixed with `_service.` (like `_service.local.yaml`) are reserved for future local overrides and are ignored during loading.
+
+## Comparison with ketacli
+
+| Feature | cliyard | ketacli |
+|---------|---------|---------|
+| API scope | Any REST API | KetaDB only |
+| Config format | One directory per API service | Single YAML tree per resource |
+| Auth model | Chain-based (env, login, inject) | Built-in, KetaDB-specific |
+| Auth caching | In-memory TTL token cache | Session-based |
+| Param types | string, int, float, bool, enum | Pre-defined per command |
+| Adding resources | Add a YAML file to the directory | Requires code changes |
+| CLI generation | Dynamic from spec at runtime | Pre-built Click commands |
+| Purpose | General-purpose API-to-CLI framework | KetaDB management tool |
+
+## Creating Your Own Spec
+
+See [examples/README.md](examples/README.md) for a step-by-step guide to creating new API specs.
+
+## License
+
+MIT

cliyard-0.3.2/README.md

@@ -0,0 +1,92 @@
+# cliyard
+
+**CLI + YAML + Yard** — a framework that generates CLI commands from YAML specs. Define your REST API in a few YAML files, and cliyard produces a fully-structured Click CLI with parameters, types, and auto-generated help. Originally inspired by [ketacli](https://gitee.com/xishuhq/ketacli)'s YAML-driven architecture, now generalized for any REST API.
+
+## Installation
+
+```bash
+pip install cliyard
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Explore the example spec
+cliyard --spec-dir examples/ketacli-repos/ repos list --help
+
+# Usage: repos list [OPTIONS]
+#   --page INTEGER        Page number
+#   --search TEXT         Search keyword
+#   --help                Show this message and exit.
+```
+
+## How It Works
+
+cliyard turns a directory of YAML files into CLI commands. One directory equals one API service. Each YAML file (except `_service.yaml`) becomes a resource group with subcommands for every defined method.
+
+```
+your-api/                          ┌─────────────────────────────────┐
+├── _service.yaml  ── service ──►  │  cliyard Engine                 │
+├── repos.yaml     ── resource ──► │                                 │
+├── users.yaml     ── resource ──► │  Loader ──► Builder ──► Click   │
+└── ...                            │    │            │           │    │
+                                   │    │     Auth Chain          │    │
+                                   │    ▼            ▼           ▼    │
+                                   │  YAML       Commands    CLI run  │
+                                   │  parsing    + params              │
+                                   └─────────────────────────────────┘
+```
+
+**Data flow** for a single invocation:
+
+```
+cliyard --spec-dir examples/ketacli-repos/ repos list --page 1
+
+    1. Loader reads _service.yaml + repos.yaml
+    2. Auth chain runs (env → login → inject token)
+    3. Builder generates Click commands from method specs
+    4. Params are typed (int, string, enum, bool) and validated
+    5. (Future) HTTP request is assembled and sent
+    6. (Future) Response is formatted with Rich tables
+```
+
+## Directory Structure
+
+Each service is a directory containing a `_service.yaml` for service-level config and one YAML file per resource:
+
+```
+ketacli-repos/
+├── _service.yaml      # Service config: name, server, auth
+└── repos.yaml         # Resource: repos (list, create, get, update, delete)
+```
+
+- `_service.yaml` defines the server URL, authentication chain, and global settings.
+- Resource files (`repos.yaml`, `users.yaml`, etc.) define the methods, parameters, and output format for each API resource.
+- Files prefixed with `_service.` (like `_service.local.yaml`) are reserved for future local overrides and are ignored during loading.
+
+## Comparison with ketacli
+
+| Feature | cliyard | ketacli |
+|---------|---------|---------|
+| API scope | Any REST API | KetaDB only |
+| Config format | One directory per API service | Single YAML tree per resource |
+| Auth model | Chain-based (env, login, inject) | Built-in, KetaDB-specific |
+| Auth caching | In-memory TTL token cache | Session-based |
+| Param types | string, int, float, bool, enum | Pre-defined per command |
+| Adding resources | Add a YAML file to the directory | Requires code changes |
+| CLI generation | Dynamic from spec at runtime | Pre-built Click commands |
+| Purpose | General-purpose API-to-CLI framework | KetaDB management tool |
+
+## Creating Your Own Spec
+
+See [examples/README.md](examples/README.md) for a step-by-step guide to creating new API specs.
+
+## License
+
+MIT

cliyard-0.3.2/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "cliyard"
+version = "0.3.2"
+description = "YAML-driven CLI framework — turn any REST API into CLI commands"
+authors = [
+    {name = "keta", email = "dev@ketaops.cc"},
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["cli", "yaml", "rest-api", "codegen", "click"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "click>=8.1.0",
+    "pyyaml~=6.0",
+    "requests~=2.31.0",
+    "jinja2~=3.1",
+    "rich>=13.7.0",
+    "jsonpath-ng~=1.7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/guolong123/cliyard"
+Repository = "https://github.com/guolong123/cliyard.git"
+
+[project.scripts]
+cliyard = "cliyard.cli.__main__:main"
+
+[build-system]
+requires = ["setuptools>=65.0.0", "wheel"]
+build-backend = "setuptools.build_meta"

cliyard-0.3.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cliyard-0.3.2/src/cliyard/__init__.py

@@ -0,0 +1,9 @@
+"""cliyard — YAML-driven CLI framework for any REST API.
+
+Quick start::
+
+    pip install cliyard
+    from cliyard.runtime import create_cli
+    cli = create_cli("./my-api-spec/")
+    cli()
+"""

cliyard-0.3.2/src/cliyard/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI entry point and command registration."""

cliyard-0.3.2/src/cliyard/cli/__main__.py

@@ -0,0 +1,96 @@
+"""cliyard CLI entry point."""
+
+import sys
+
+import click
+from click.exceptions import NoArgsIsHelpError, MissingParameter, UsageError
+
+
+def _intercept_spec_dir() -> None:
+    """If ``--spec-dir`` is in sys.argv, extract it and run the spec-based CLI.
+
+    This must happen *before* Click's command resolution because the
+    spec-driven commands (e.g. ``repos list``) don't exist as registered
+    Click subcommands — they are built dynamically from YAML specs.
+
+    Does NOT intercept if the command is ``auth``, ``gen``, ``init``, or ``run``
+    — those are native cliyard commands, not spec-driven commands.
+    """
+    if "--spec-dir" not in sys.argv:
+        return
+
+    # Skip interception for native cliyard commands
+    for arg in sys.argv[1:]:
+        if not arg.startswith("-") and arg in ("auth", "gen", "init", "run"):
+            return
+        if arg.startswith("-"):
+            continue
+        break
+
+    try:
+        idx = sys.argv.index("--spec-dir")
+    except ValueError:
+        return
+
+    if idx + 1 >= len(sys.argv):
+        click.echo("Error: --spec-dir requires a directory path", err=True)
+        sys.exit(1)
+
+    spec_dir = sys.argv[idx + 1]
+
+    sys.argv.pop(idx)
+    sys.argv.pop(idx)
+
+    from cliyard.runtime.runner import run_with_spec
+
+    run_with_spec(spec_dir)
+
+
+@click.group()
+@click.version_option()
+def cli():
+    """cliyard — YAML-driven CLI framework for any REST API.
+
+    Turn any REST API into CLI commands by writing simple YAML specs.
+    """
+
+
+@cli.command()
+def init():
+    """Initialize a new cliyard spec directory."""
+    click.echo("Not yet implemented. Stay tuned.")
+
+
+from cliyard.cli.gen import gen
+
+cli.add_command(gen)
+
+
+@cli.command()
+@click.argument("spec_file")
+@click.argument("resource")
+@click.argument("operation", required=False)
+@click.option("-e", "--extra", type=str, help="Extra args, key=val,key2=val2")
+def run(spec_file, resource, operation, extra):
+    """Run a command from a YAML spec file."""
+    click.echo(f"Not yet implemented. Would run: {spec_file} {resource} {operation}")
+
+
+def main():
+    """Entry point — intercept --spec-dir before Click, then run CLI."""
+    _intercept_spec_dir()
+    try:
+        cli(standalone_mode=False)
+    except MissingParameter as e:
+        click.echo(f"Error: {e}", err=True)
+        click.echo(f"  Usage: cliyard gen --name <name> [--defs-path <path>]")
+    except UsageError as e:
+        click.echo(f"Error: {e}", err=True)
+    except NoArgsIsHelpError as e:
+        click.echo(e.format_message())
+    except SystemExit:
+        pass
+
+
+if __name__ == "__main__":
+    main()

cliyard-0.3.2/src/cliyard/cli/auth_cmd.py

@@ -0,0 +1,167 @@
+"""cliyard.auth — Manage authentication credentials.
+
+Provides ``cliyard auth login``, ``cliyard auth status``, and
+``cliyard auth logout`` subcommands.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+
+@click.group(name="auth")
+def auth_group() -> None:
+    """Manage authentication credentials.
+
+    Login to a service, check saved credential status, or clear
+    saved credentials.
+    """
+
+
+@auth_group.command(name="login")
+@click.option("--spec-dir", required=True, help="Path to YAML spec directory")
+def auth_login(spec_dir: str) -> None:
+    """Initialize auth credentials by running the auth chain.
+
+    Reads the auth spec from ``_auth.yaml``, executes all auth steps,
+    and persists the resulting tokens according to the ``auth.persist``
+    configuration.
+    """
+    from cliyard.client.auth import run_auth_chain
+    from cliyard.client.credentials import save_service_credentials
+    from cliyard.engine.loader import load_service
+
+    console = Console()
+    spec_path = Path(spec_dir).resolve()
+
+    try:
+        service = load_service(spec_path)
+    except Exception as exc:
+        console.print(f"[red]Error loading spec: {exc}[/red]")
+        return
+
+    auth_spec = service.get("auth")
+    if not auth_spec:
+        console.print("[red]No auth config found in _auth.yaml[/red]")
+        return
+
+    # Run the auth chain (no pre-filled — full re-login)
+    try:
+        from cliyard.client.http import HttpClient
+
+        server = service.get("server", {})
+        base_url = server.get("base_url", "http://localhost:8080")
+        client = HttpClient(base_url)
+        auth_state = run_auth_chain(auth_spec, http_client=client)
+    except Exception as exc:
+        console.print(f"[red]Auth failed: {exc}[/red]")
+        return
+
+    # Save based on persist config
+    persist = auth_spec.get("persist", {})
+    if persist.get("to") == "cliyard-config" or not persist.get("to"):
+        service_id = auth_spec.get("id", service.get("name", "default"))
+        fields: dict[str, str | int] = {}
+
+        persist_fields = persist.get("fields", {})
+        for field_name, field_config in persist_fields.items():
+            ref: str = field_config.get("from", "")
+            default = field_config.get("default")
+
+            if "." in ref:
+                step, key = ref.split(".", 1)
+                step_value = auth_state.get(step)
+                if isinstance(step_value, dict):
+                    value = step_value.get(key)
+                else:
+                    value = None
+                if value is not None:
+                    fields[field_name] = value
+                elif default is not None:
+                    fields[field_name] = default
+            else:
+                # Direct reference: field_name = step_name
+                value = auth_state.get(ref)
+                if value is not None:
+                    fields[field_name] = value
+                elif default is not None:
+                    fields[field_name] = default
+
+        # Auto-compute expires_at from ttl if present
+        # Look for a "ttl" key in the extracted auth state
+        ttl_value: int | None = None
+        for step_name, step_value in auth_state.items():
+            if isinstance(step_value, dict) and "ttl" in step_value:
+                ttl_value = step_value["ttl"]
+                break
+        if ttl_value:
+            fields["expires_at"] = int(time.time()) + int(ttl_value)
+
+        if fields:
+            save_service_credentials(service_id, fields)
+            console.print(f"[green]Credentials saved for '{service_id}'[/green]")
+        else:
+            console.print("[yellow]No fields configured for persistence.[/yellow]")
+            console.print(f"[dim]auth_state: {auth_state}[/dim]")
+    else:
+        console.print(f"[yellow]Persistence target {persist.get('to')!r} not supported yet.[/yellow]")
+
+
+@auth_group.command(name="status")
+def auth_status() -> None:
+    """Show saved authentication status."""
+    from cliyard.client.credentials import load_credentials
+
+    console = Console()
+    creds = load_credentials()
+    services = creds.get("services", {})
+    if not services:
+        console.print("[yellow]No credentials saved.[/yellow]")
+        return
+
+    table = Table()
+    table.add_column("Service")
+    table.add_column("Fields")
+    table.add_column("Expires")
+
+    for svc_id, fields in services.items():
+        field_names = [k for k in fields.keys() if k != "expires_at"]
+        expires_at = fields.get("expires_at")
+        if expires_at:
+            remaining = int(expires_at) - int(time.time())
+            if remaining > 0:
+                hours = remaining // 3600
+                minutes = (remaining % 3600) // 60
+                expiry = f"{hours}h {minutes}m remaining"
+            else:
+                expiry = "[red]EXPIRED[/red]"
+        else:
+            expiry = "never"
+        table.add_row(svc_id, ", ".join(field_names), expiry)
+
+    console.print(table)
+
+
+@auth_group.command(name="logout")
+@click.option("--service", "-s", help="Service ID to logout (default: all)")
+def auth_logout(service: str | None) -> None:
+    """Clear saved credentials."""
+    console = Console()
+    if service:
+        from cliyard.client.credentials import clear_service_credentials
+
+        clear_service_credentials(service)
+        console.print(f"[green]Credentials cleared for '{service}'[/green]")
+    else:
+        creds_path = os.path.expanduser("~/.cliyard/credentials.yaml")
+        if os.path.exists(creds_path):
+            os.remove(creds_path)
+            console.print("[green]All credentials cleared.[/green]")
+        else:
+            console.print("[yellow]No credentials to clear.[/yellow]")