cliyard 0.3.2__py3-none-any.whl

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/cli/__init__.py

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

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/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]")

cliyard/cli/gen.py

@@ -0,0 +1,412 @@
+"""``cliyard gen`` — Generate a standalone CLI tool from YAML specs.
+
+Usage::
+
+    cliyard gen --name ketacliv2 --defs-path tests/fixtures/spec-dir/
+    cd dist/ketacliv2 && pip install -e .
+    ketacliv2 repos list --help
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+import yaml  # noqa: F401 — used in gen() for parsing resource YAMLs
+
+import click
+
+_PYPROJECT_TOML_TEMPLATE = """\
+[project]
+name = "{CLI_NAME}"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = ["cliyard>=0.1.0"]
+
+[project.scripts]
+{CLI_NAME} = "{pkg_name}.main:main"
+
+[build-system]
+requires = ["setuptools>=65.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"{pkg_name}" = ["specs/*.yaml", "specs/plugins/*.py", "specs/plugins/spl_parser/*.py"]
+"""
+
+_MAIN_PY_TEMPLATE = """\
+\"\"\"CLI entry point. Edit this file to customize commands.\"\"\"
+import sys
+from pathlib import Path
+try:
+    from importlib.metadata import version, PackageNotFoundError
+    _VER = version("{pkg_name}")
+except PackageNotFoundError:
+    _VER = "0.0.0"
+from click.exceptions import UsageError
+from cliyard.runtime import create_cli
+
+_SPEC_DIR = Path(__file__).parent / "specs"
+
+
+def main():
+    try:
+        cli = create_cli(str(_SPEC_DIR), version=_VER)
+        sys.exit(cli(standalone_mode=False))
+    except UsageError as e:
+        sys.exit(e.format_message())
+"""
+_INIT_PY = ""
+
+_README_TEMPLATE = """\
+# {CLI_NAME}
+
+Generated by [cliyard](https://github.com/example/cliyard).
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Show available commands
+{CLI_NAME} --help
+
+# Authenticate (first time)
+{CLI_NAME} auth add -n myenv -e <endpoint> -u <user> -p <pass>
+
+# Or use an existing token
+{CLI_NAME} auth add -n myenv -e <endpoint> -t <token>
+
+# Run commands
+{CLI_NAME} <resource> list --page-size 10
+{CLI_NAME} <resource> list --format json
+```
+
+## Adding new resources
+
+1. Create a YAML file in `src/{pkg_name}/specs/` (copy an existing one as reference):
+
+```yaml
+description: My resource
+path: myresource
+methods:
+  list:
+    http:
+      method: GET
+    output:
+      items_path: $.items
+      fields:
+        - name: id
+          alias: ID
+  create:
+    http:
+      method: POST
+    params:
+      body:
+        - name: name
+          type: string
+          required: true
+```
+
+2. Re-run `cliyard gen --name {CLI_NAME}` in the project directory to regenerate the CLI.
+
+## Customizing commands
+
+To add custom logic or new commands, use the plugin system instead of editing ``main.py``:
+
+```python
+# src/{pkg_name}/specs/plugins/my_custom.py
+from cliyard.plugin import register_command
+
+@register_command("mycmd")
+def register_mycmd(cli, ctx):
+    @click.command("mycmd")
+    @click.argument("input")
+    def mycmd(input):
+        click.echo(f"Input: {input}")
+    cli.add_command(mycmd)
+```
+
+See the **Top-level command plugins** section below for details.
+
+## Adding plugins
+
+Create a `.py` file in `src/{pkg_name}/specs/plugins/`:
+
+```python
+from cliyard.plugin import register_auth_step, register_hook
+
+@register_auth_step("custom_login")
+class CustomLogin:
+    def execute(self, auth_state, config, http_client):
+        # Custom auth logic
+        token = "my-token"
+        http_client.default_headers["Authorization"] = f"Bearer {token}"
+        auth_state["token"] = token
+        return token
+
+@register_hook("custom_hook")
+def custom_hook(req):
+    req.headers["X-Custom"] = "value"
+    return req
+```
+
+Reference plugins in `_auth.yaml`:
+
+```yaml
+auth:
+  steps:
+    - name: login
+      type: plugin:custom_login
+```
+
+## Custom method plugins
+
+For business logic that involves multiple API calls, write a method plugin:
+
+```python
+# src/{pkg_name}/specs/plugins/my_biz.py
+from cliyard.plugin import register_method
+
+@register_method("multi_step_import")
+def multi_step_import(params, http_client, config):
+    # Step 1: prepare
+    r1 = http_client.request("POST", "/api/prepare", data=params)
+    # Step 2: transform and commit
+    r2 = http_client.request("POST", "/api/commit", json=r1.json())
+    return {"status": "done", "id": r2.json().get("id")}
+```
+
+Reference it in a resource YAML:
+
+```yaml
+methods:
+  import:
+    type: plugin:multi_step_import
+    config:
+      batch_size: 100
+    params:
+      body:
+        - name: source
+          type: string
+          required: true
+```
+
+The plugin function receives ``params`` (validated CLI args), ``http_client``
+(authenticated), and ``config`` (from YAML). The return value is JSON output.
+
+## Top-level command plugins
+
+For standalone commands that don't belong to any resource group (e.g. ``search``,
+``mock``, ``insert``), use ``@register_command``:
+
+```python
+# src/{pkg_name}/specs/plugins/mycmd.py
+import click
+from cliyard.plugin import register_command
+
+@register_command("mycmd")
+def register_mycmd(cli, ctx):
+    @click.command("mycmd")
+    @click.argument("input")
+    @click.option("--verbose", is_flag=True)
+    def mycmd(input, verbose):
+        \"\"\"My custom top-level command.\"\"\"
+        click.echo(f"Input: {input}")
+
+    cli.add_command(mycmd)
+```
+
+The function receives the top-level ``cli`` (``click.Group``) and ``ctx``
+(``ServiceContext`` containing base_url, auth config, etc.). Call
+``cli.add_command(...)`` with your built Click command.
+
+### Available plugin decorators
+
+| Decorator | Purpose |
+|-----------|---------|
+| ``@register_auth_step("name")`` | Custom authentication step (referenced in ``_auth.yaml``) |
+| ``@register_field_type("name")`` | Custom field type validator |
+| ``@register_hook("name")`` | Pre/post request hook |
+| ``@register_method("name")`` | Multi-step business method (referenced in YAML via ``type: plugin:xxx``) |
+| ``@register_command("name")`` | **Top-level Click command** (not tied to any resource) |
+| ``@register_field_resolver("name")`` | Dynamic field value resolver (e.g. auto-fill version) |
+
+## Multiple environments
+
+```bash
+# Add environments
+{CLI_NAME} auth add -n dev -e https://dev.example.com -t <token>
+{CLI_NAME} auth add -n prod -e https://prod.example.com -t <token> --default
+
+# Switch between them
+{CLI_NAME} auth switch prod
+{CLI_NAME} --env prod <resource> list
+```
+
+## Multi-server configuration
+
+When an API is composed of multiple services at different endpoints,
+declare them in ``_auth.yaml`` without hardcoding ``base_url``:
+
+```yaml
+server:
+  - name: serve4go
+    prefix: /api/v1
+  - name: serve4java
+    prefix: /api/v2
+```
+
+The ``name`` fields dynamically generate ``--server-<name>`` options on
+``auth add``. Endpoints are provided at authentication time:
+
+```bash
+# Multi-server: one URL per server
+{CLI_NAME} auth add -n prod \\
+  --server-serve4go https://go-api.example.com \\
+  --server-serve4java https://java-api.example.com
+
+# Single server: use -e as fallback
+{CLI_NAME} auth add -n prod -e https://api.example.com
+```
+
+Resources select their server via the ``server:`` field:
+
+```yaml
+# repos.yaml — uses the default (first) server
+description: 仓库管理
+path: repos
+
+# alerts.yaml — uses the "serve4java" server
+server: serve4java
+description: 告警规则
+path: alerts
+```
+
+If a resource does not specify ``server:``, it uses the first server
+in the list. Auth steps can also specify a ``server:`` field to
+choose which endpoint to authenticate against.
+"""
+
+
+@click.command()
+@click.option("--name", required=True, help="Name of the generated CLI tool")
+@click.option(
+    "--defs-path",
+    default=None,
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    help="Path to YAML spec directory (omit for empty scaffold)",
+)
+@click.option(
+    "--output",
+    default=None,
+    type=click.Path(file_okay=False, resolve_path=True),
+    help="Output directory (default: ./<name>/)",
+)
+def gen(name: str, defs_path: str | None, output: str | None) -> None:
+    """Generate a standalone CLI tool from YAML specs.
+
+    Reads a cliyard service spec directory (containing ``_auth.yaml``
+    and resource YAML files) and produces a pip-installable Python package
+    in the output directory. If ``--defs-path`` is omitted, generates an
+    empty scaffold that you can fill in later.
+    """
+    pkg_name = name.replace("-", "_")
+    output_dir = Path(output) if output else Path.cwd() / name
+    output_dir = output_dir.resolve()
+
+    # Create output structure
+    src_dir = output_dir / "src" / pkg_name
+    specs_dir = src_dir / "specs"
+    specs_dir.mkdir(parents=True, exist_ok=True)
+
+    click.echo(f"✔ Created output directory: {output_dir}")
+
+    # 1. Validate or create defs-path
+    if defs_path:
+        spec_dir = Path(defs_path).resolve()
+        service_yaml = spec_dir / "_auth.yaml"
+        if not service_yaml.exists():
+            click.echo(f"Error: {spec_dir} does not contain _auth.yaml", err=True)
+            sys.exit(1)
+        click.echo(f"✔ Found _auth.yaml in {spec_dir}")
+    else:
+        # No --defs-path: check if output specs/ already has YAMLs
+        existing_svc = specs_dir / "_auth.yaml"
+        if existing_svc.exists():
+            spec_dir = specs_dir  # Regenerate from existing specs
+            click.echo(f"✔ Reusing specs from {specs_dir}")
+        else:
+            spec_dir = None
+            # Generate a minimal _auth.yaml for the scaffold
+            scaffold_svc = specs_dir / "_auth.yaml"
+            scaffold_svc.write_text(f"""\
+name: {name}
+version: "0.1.0"
+description: CLI for {name}
+server:
+  base_url: http://localhost:8080
+""")
+            click.echo("✔ Generated empty scaffold (add YAMLs to src/{pkg_name}/specs/)")
+
+    # 2. Generate pyproject.toml
+
+    # 3. Generate pyproject.toml
+    pyproject_path = output_dir / "pyproject.toml"
+    pyproject_path.write_text(
+        _PYPROJECT_TOML_TEMPLATE
+        .replace("{CLI_NAME}", name)
+        .replace("{pkg_name}", pkg_name)
+    )
+    click.echo(f"✔ Generated pyproject.toml")
+
+    # 4. Generate src/<pkg_name>/__init__.py
+    init_path = src_dir / "__init__.py"
+    init_path.write_text(_INIT_PY)
+    click.echo(f"✔ Generated src/{pkg_name}/__init__.py")
+
+    # 5. Generate src/<pkg_name>/main.py (thin wrapper around create_cli)
+    main_path = src_dir / "main.py"
+    main_path.write_text(_MAIN_PY_TEMPLATE.format(pkg_name=pkg_name))
+    click.echo(f"✔ Generated src/{pkg_name}/main.py")
+
+    # 6. Copy spec files (skip if already in specs_dir)
+    copied = 0
+    if spec_dir and spec_dir.resolve() != specs_dir.resolve():
+        for yaml_file in sorted(spec_dir.glob("*.yaml")):
+            dest = specs_dir / yaml_file.name
+            shutil.copy2(yaml_file, dest)
+            copied += 1
+    elif spec_dir and spec_dir.resolve() == specs_dir.resolve():
+        copied = len(list(spec_dir.glob("*.yaml")))  # Already in place
+    click.echo(f"✔ Copied {copied} spec file(s) to src/{pkg_name}/specs/")
+
+    # 6b. Copy plugins directory if it exists
+    if spec_dir:
+        plugins_src = spec_dir / "plugins"
+        if plugins_src.is_dir():
+            plugins_dest = specs_dir / "plugins"
+            shutil.copytree(plugins_src, plugins_dest, dirs_exist_ok=True)
+            click.echo(f"✔ Copied plugins/ to src/{pkg_name}/specs/plugins/")
+
+    # 7. Generate README.md
+    readme_path = output_dir / "README.md"
+    readme_path.write_text(
+        _README_TEMPLATE
+        .replace("{CLI_NAME}", name)
+        .replace("{pkg_name}", pkg_name)
+    )
+    click.echo(f"✔ Generated README.md")
+
+    click.echo()
+    click.echo(f"Package generated at {output_dir}")
+    click.echo(f"To install:  cd {output_dir} && pip install -e .")
+    click.echo(f"To use:      {name} --help")

cliyard/client/__init__.py

@@ -0,0 +1,4 @@
+from cliyard.client.http import ApiError
+from cliyard.client.http import request
+
+__all__ = ["ApiError", "request"]