fulfil-cli 0.1.0__py3-none-any.whl

fulfil_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Fulfil CLI — primary interface for humans and AI agents."""
+
+__version__ = "0.1.0"

fulfil_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m fulfil_cli`."""
+
+from fulfil_cli.cli import main
+
+main()

fulfil_cli/auth/api_key.py

@@ -0,0 +1,76 @@
+"""API key resolution — env > flag > keyring."""
+
+from __future__ import annotations
+
+import os
+
+from fulfil_cli.auth.keyring_store import get_api_key
+from fulfil_cli.client.errors import AuthError
+
+
+def resolve_api_key(
+    *,
+    token_flag: str | None = None,
+    workspace: str | None = None,
+) -> str:
+    """Resolve API key from: --token flag > FULFIL_API_KEY env > keyring.
+
+    Raises AuthError if no key can be found.
+    """
+    # 1. Explicit --token flag
+    if token_flag:
+        return token_flag
+
+    # 2. Environment variable
+    env_key = os.environ.get("FULFIL_API_KEY")
+    if env_key:
+        return env_key
+
+    # 3. Keyring (requires workspace)
+    if workspace:
+        stored = get_api_key(workspace)
+        if stored:
+            return stored
+
+    raise AuthError(
+        message="No API key found",
+        hint="Run 'fulfil auth login' or set FULFIL_API_KEY environment variable.",
+    )
+
+
+def resolve_workspace(
+    *,
+    workspace_flag: str | None = None,
+    config_workspace: str | None = None,
+) -> str:
+    """Resolve workspace from: --workspace flag > FULFIL_WORKSPACE env > config.
+
+    The workspace is the full domain (e.g. 'acme.fulfil.io').
+    Raises AuthError if no workspace can be found.
+    """
+    if workspace_flag:
+        return _normalize_workspace(workspace_flag)
+
+    env_workspace = os.environ.get("FULFIL_WORKSPACE")
+    if env_workspace:
+        return _normalize_workspace(env_workspace)
+
+    if config_workspace:
+        return config_workspace
+
+    raise AuthError(
+        message="No workspace configured",
+        hint="Run 'fulfil auth login' or set FULFIL_WORKSPACE environment variable.",
+    )
+
+
+def _normalize_workspace(value: str) -> str:
+    """Normalize workspace input — accept slug or full domain.
+
+    'acme' → 'acme.fulfil.io'
+    'acme.fulfil.io' → 'acme.fulfil.io'
+    'acme.fulfil.app' → 'acme.fulfil.app'
+    """
+    if "." in value:
+        return value
+    return f"{value}.fulfil.io"

fulfil_cli/auth/keyring_store.py

@@ -0,0 +1,25 @@
+"""Keyring-based storage for API keys."""
+
+from __future__ import annotations
+
+import contextlib
+
+import keyring
+
+SERVICE_NAME = "fulfil-cli"
+
+
+def store_api_key(workspace: str, api_key: str) -> None:
+    """Store an API key in the system keyring."""
+    keyring.set_password(SERVICE_NAME, workspace, api_key)
+
+
+def get_api_key(workspace: str) -> str | None:
+    """Retrieve an API key from the system keyring."""
+    return keyring.get_password(SERVICE_NAME, workspace)
+
+
+def delete_api_key(workspace: str) -> None:
+    """Delete an API key from the system keyring."""
+    with contextlib.suppress(keyring.errors.PasswordDeleteError):
+        keyring.delete_password(SERVICE_NAME, workspace)

fulfil_cli/cli/__init__.py

@@ -0,0 +1,7 @@
+"""CLI entry point."""
+
+from fulfil_cli.cli.app import app
+
+
+def main() -> None:
+    app()

fulfil_cli/cli/app.py

@@ -0,0 +1,248 @@
+"""Root CLI application with dynamic model subcommands."""
+
+from __future__ import annotations
+
+import click
+import typer
+import typer.core
+from rich.console import Console
+
+from fulfil_cli import __version__
+from fulfil_cli.cli.commands import auth, config
+from fulfil_cli.cli.commands.api import api_cmd
+from fulfil_cli.cli.commands.completion import completion_install
+from fulfil_cli.cli.commands.model import create_model_group
+from fulfil_cli.cli.commands.report import create_report_group
+from fulfil_cli.cli.state import get_client, is_quiet, set_globals
+from fulfil_cli.client.errors import FulfilError
+from fulfil_cli.output.formatter import output
+
+console = Console(stderr=True)
+
+
+def _handle_error(exc: FulfilError) -> None:
+    """Print error and exit with appropriate code."""
+    console.print(f"[red]Error: {exc}[/red]")
+    if exc.hint and not is_quiet():
+        console.print(f"[dim]Hint: {exc.hint}[/dim]")
+    raise typer.Exit(code=exc.exit_code)
+
+
+class ReportGroup(click.Group):
+    """Click group that resolves unknown subcommands as report names."""
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        rv = super().get_command(ctx, cmd_name)
+        if rv is not None:
+            return rv
+        return create_report_group(cmd_name)
+
+
+class FulfilGroup(typer.core.TyperGroup):
+    """Custom Click group that resolves unknown subcommands as model or report names."""
+
+    # Dynamic commands that should appear in help alongside static ones
+    _dynamic_commands = ("models", "reports")
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        commands = super().list_commands(ctx)
+        for name in self._dynamic_commands:
+            if name not in commands:
+                commands.append(name)
+        return commands
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        # Check static commands first
+        rv = super().get_command(ctx, cmd_name)
+        if rv is not None:
+            return rv
+        # `fulfil models` / `fulfil models list`
+        if cmd_name == "models":
+            return models_group
+        # `fulfil reports` / `fulfil reports list` / `fulfil reports <name> execute`
+        if cmd_name == "reports":
+            return reports_group
+        # Treat as model name → return model sub-group
+        return create_model_group(cmd_name)
+
+
+app = typer.Typer(
+    cls=FulfilGroup,
+    name="fulfil",
+    help=(
+        "The Fulfil CLI — interact with the Fulfil ERP platform from the command line.\n\n"
+        "Any Fulfil model name (e.g. sales_order, product, customer_shipment) is a valid\n"
+        "subcommand. Each model supports: list, get, create, update, delete, count, call,\n"
+        "and describe.\n\n"
+        "Examples:\n\n"
+        "  # List confirmed sales orders\n"
+        '  fulfil sales_order list --where \'{"state": "confirmed"}\'\n\n'
+        "  # Get a specific product by ID\n"
+        "  fulfil product get 42\n\n"
+        "  # Create a new contact\n"
+        '  fulfil contact create --data \'{"name": "Acme Corp"}\'\n\n'
+        "  # Count open shipments\n"
+        '  fulfil customer_shipment count --where \'{"state": "waiting"}\'\n\n'
+        "  # Send a raw JSON-RPC call\n"
+        '  fulfil api \'{"method": "system.version", "params": {}}\'\n\n'
+        "  # List available models\n"
+        "  fulfil models"
+    ),
+    no_args_is_help=True,
+    add_completion=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+# Static command groups
+app.add_typer(auth.app, name="auth")
+app.add_typer(config.app, name="config")
+
+
+@app.callback()
+def main_callback(
+    ctx: typer.Context,
+    token: str | None = typer.Option(None, "--token", envvar="FULFIL_API_KEY", help="API key"),
+    workspace: str | None = typer.Option(
+        None,
+        "--workspace",
+        envvar="FULFIL_WORKSPACE",
+        help="Workspace domain (e.g. acme.fulfil.io)",
+    ),
+    base_url: str | None = typer.Option(None, "--base-url", hidden=True, help="Override base URL"),
+    debug: bool = typer.Option(False, "--debug", help="Show debug output"),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress hints and decorative output"),
+) -> None:
+    """Root callback — sets global auth state."""
+    set_globals(token=token, workspace=workspace, base_url=base_url, debug=debug, quiet=quiet)
+
+
+@app.command()
+def version(
+    json_flag: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    """Show CLI version."""
+    if json_flag:
+        output({"version": __version__}, json_flag=True)
+    else:
+        typer.echo(f"fulfil-cli {__version__}")
+
+
+@app.command()
+def whoami(
+    json_flag: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    """Show current user and workspace info."""
+    try:
+        client = get_client()
+        result = client.call("system.whoami")
+    except FulfilError as exc:
+        _handle_error(exc)
+
+    output(result, json_flag=json_flag)
+
+
+def _flatten_model_row(row: dict) -> dict:
+    """Pick key columns and flatten access dict for table display."""
+    access = row.get("access", {})
+    return {
+        "model": row.get("model_name", ""),
+        "description": row.get("description", ""),
+        "category": row.get("category", ""),
+        "read": access.get("read", False),
+        "create": access.get("create", False),
+        "update": access.get("update", False),
+        "delete": access.get("delete", False),
+    }
+
+
+def _list_models(json_flag: bool, search: str | None = None) -> None:
+    """Fetch and display all available models."""
+    try:
+        client = get_client()
+        result = client.call("system.list_models")
+    except FulfilError as exc:
+        _handle_error(exc)
+
+    if search and isinstance(result, list):
+        term = search.lower()
+        result = [
+            r
+            for r in result
+            if isinstance(r, dict)
+            and (
+                term in r.get("model_name", "").lower()
+                or term in r.get("description", "").lower()
+                or term in r.get("category", "").lower()
+            )
+        ]
+
+    if not json_flag and isinstance(result, list):
+        result = [_flatten_model_row(r) for r in result if isinstance(r, dict)]
+
+    output(result, json_flag=json_flag, title="Available Models")
+
+
+@click.group(name="models", help="List available models.", invoke_without_command=True)
+@click.option("--json", "json_flag", is_flag=True, help="Output as JSON")
+@click.option("--search", "-s", default=None, help="Filter by name, description, or category.")
+@click.pass_context
+def models_group(ctx: click.Context, json_flag: bool, search: str | None) -> None:
+    """List all available models."""
+    ctx.ensure_object(dict)
+    ctx.obj["json_flag"] = json_flag
+    ctx.obj["search"] = search
+    if ctx.invoked_subcommand is None:
+        _list_models(json_flag, search=search)
+
+
+@models_group.command("list")
+@click.option("--json", "json_flag", is_flag=True, help="Output as JSON")
+@click.option("--search", "-s", default=None, help="Filter by name, description, or category.")
+@click.pass_context
+def models_list_cmd(ctx: click.Context, json_flag: bool, search: str | None) -> None:
+    """List all available models."""
+    _list_models(json_flag, search=search)
+
+
+def _list_reports(json_flag: bool) -> None:
+    """Fetch and display all available reports."""
+    try:
+        client = get_client()
+        result = client.call("system.list_reports")
+    except FulfilError as exc:
+        _handle_error(exc)
+
+    output(result, json_flag=json_flag, title="Available Reports")
+
+
+@click.group(
+    name="reports",
+    cls=ReportGroup,
+    help="Interact with reports.",
+    invoke_without_command=True,
+)
+@click.option("--json", "json_flag", is_flag=True, help="Output as JSON")
+@click.pass_context
+def reports_group(ctx: click.Context, json_flag: bool) -> None:
+    """List all available reports."""
+    ctx.ensure_object(dict)
+    ctx.obj["json_flag"] = json_flag
+    if ctx.invoked_subcommand is None:
+        _list_reports(json_flag)
+
+
+@reports_group.command("list")
+@click.option("--json", "json_flag", is_flag=True, help="Output as JSON")
+@click.pass_context
+def reports_list_cmd(ctx: click.Context, json_flag: bool) -> None:
+    """List all available reports."""
+    _list_reports(json_flag)
+
+
+# Register standalone commands
+app.command(name="api")(api_cmd)
+app.command(name="completion")(completion_install)
+
+
+# Top-level aliases for frequently-used auth subcommands
+app.command(name="workspaces")(auth.workspaces)

fulfil_cli/cli/commands/api.py

@@ -0,0 +1,63 @@
+"""Raw JSON-RPC call command."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+from rich.console import Console
+
+from fulfil_cli.cli.state import get_client
+from fulfil_cli.client.errors import FulfilError
+from fulfil_cli.output.formatter import output
+
+console = Console(stderr=True)
+
+
+def api_cmd(
+    payload: str = typer.Argument(
+        ...,
+        help=(
+            "JSON-RPC request body (or '-' to read from stdin). "
+            'Must contain a "method" key and optional "params" object. '
+            """Example: '{"method": "system.version", "params": {}}'"""
+        ),
+    ),
+    json_flag: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    """Send a raw JSON-RPC request to the Fulfil API.
+
+    \b
+    Examples:
+      fulfil api '{"method": "system.version", "params": {}}'
+      fulfil api '{"method": "model.sale_order.find", "params": {"where": {"state": "confirmed"}}}'
+      echo '{"method": "system.version", "params": {}}' | fulfil api -
+    """
+    if payload == "-":
+        payload = sys.stdin.read()
+
+    try:
+        data = json.loads(payload)
+    except json.JSONDecodeError as exc:
+        console.print(f"[red]Invalid JSON: {exc}[/red]")
+        raise typer.Exit(code=7) from None
+
+    # Extract method and params from JSON-RPC envelope or shorthand
+    if "method" in data:
+        method = data["method"]
+        params = data.get("params", {})
+    else:
+        console.print("[red]JSON must contain a 'method' key.[/red]")
+        raise typer.Exit(code=2)
+
+    try:
+        client = get_client()
+        result = client.call(method, **params)
+    except FulfilError as exc:
+        console.print(f"[red]Error: {exc}[/red]")
+        if exc.hint:
+            console.print(f"[dim]Hint: {exc.hint}[/dim]")
+        raise typer.Exit(code=exc.exit_code) from None
+
+    output(result, json_flag=json_flag)

fulfil_cli/cli/commands/auth.py

@@ -0,0 +1,167 @@
+"""Auth commands: login, logout, status, token, workspaces, use."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import typer
+from rich.console import Console
+
+from fulfil_cli.auth.api_key import resolve_api_key, resolve_workspace
+from fulfil_cli.auth.keyring_store import delete_api_key, get_api_key, store_api_key
+from fulfil_cli.client.errors import AuthError, FulfilError
+from fulfil_cli.client.http import FulfilClient
+from fulfil_cli.config.manager import ConfigManager
+
+app = typer.Typer(help="Manage authentication.")
+console = Console()
+
+
+@app.command()
+def login(
+    workspace: str | None = typer.Option(None, help="Workspace domain (e.g. 'acme.fulfil.io')"),
+    api_key: str | None = typer.Option(None, "--api-key", help="API key"),
+) -> None:
+    """Authenticate with a Fulfil workspace."""
+    config = ConfigManager()
+
+    if not workspace:
+        workspace = typer.prompt("Workspace domain (e.g. acme.fulfil.io)")
+    if not api_key:
+        api_key = typer.prompt("API key", hide_input=True)
+
+    # Normalize workspace — accept slug or full domain
+    if "." not in workspace:
+        workspace = f"{workspace}.fulfil.io"
+
+    # Validate the credentials
+    console.print(f"[dim]Validating credentials for {workspace}...[/dim]")
+    try:
+        client = FulfilClient(workspace=workspace, api_key=api_key)
+        client.call("system.version")
+    except FulfilError as exc:
+        console.print(f"[red]Authentication failed: {exc}[/red]")
+        raise typer.Exit(code=exc.exit_code) from None
+    except Exception:
+        # If the v3 endpoint doesn't exist yet, store anyway with a warning
+        console.print(
+            "[yellow]Warning: Could not validate credentials "
+            "(v3 API may not be deployed yet).[/yellow]"
+        )
+
+    # Store credentials
+    store_api_key(workspace, api_key)
+    config.add_workspace(workspace)
+    config.workspace = workspace
+    console.print(f"[green]Logged in to workspace '{workspace}'.[/green]")
+
+
+@app.command()
+def logout(
+    workspace: str | None = typer.Argument(
+        None, help="Workspace to log out from (default: current)"
+    ),
+    all_workspaces: bool = typer.Option(False, "--all", help="Log out from all workspaces"),
+) -> None:
+    """Remove stored credentials."""
+    config = ConfigManager()
+
+    if all_workspaces:
+        for ws in config.workspaces:
+            delete_api_key(ws)
+        config.clear_workspaces()
+        console.print("[green]Logged out from all workspaces.[/green]")
+        return
+
+    target = workspace or config.workspace
+    if target:
+        delete_api_key(target)
+        config.remove_workspace(target)
+        if config.workspace == target:
+            # Switch to another workspace if available, or clear
+            remaining = config.workspaces
+            config.workspace = remaining[0] if remaining else None
+        console.print(f"[green]Logged out from '{target}'.[/green]")
+    else:
+        console.print("[dim]Not logged in.[/dim]")
+
+
+@app.command()
+def status() -> None:
+    """Show current authentication status."""
+    config = ConfigManager()
+    workspace = config.workspace
+    if not workspace:
+        console.print("[yellow]Not logged in.[/yellow]")
+        console.print("[dim]Run 'fulfil auth login' to authenticate.[/dim]")
+        raise typer.Exit(code=3)
+
+    has_key = get_api_key(workspace) is not None
+    env_key = "FULFIL_API_KEY" in os.environ
+
+    console.print(f"Workspace: [bold]{workspace}[/bold]")
+    if env_key:
+        console.print("API Key:   [green]set via FULFIL_API_KEY[/green]")
+    elif has_key:
+        console.print("API Key:   [green]stored in keyring[/green]")
+    else:
+        console.print("API Key:   [red]not found[/red]")
+
+    all_ws = config.workspaces
+    if len(all_ws) > 1:
+        console.print(f"\nAll workspaces ({len(all_ws)}):")
+        for ws in all_ws:
+            marker = " [bold green]*[/bold green]" if ws == workspace else ""
+            console.print(f"  {ws}{marker}")
+
+
+@app.command()
+def token() -> None:
+    """Print the current API key to stdout (for piping)."""
+    config = ConfigManager()
+    try:
+        workspace = resolve_workspace(config_workspace=config.workspace)
+        key = resolve_api_key(workspace=workspace)
+    except AuthError as exc:
+        console.print(f"[red]{exc}[/red]", file=sys.stderr)
+        raise typer.Exit(code=exc.exit_code) from None
+    print(key)
+
+
+@app.command()
+def workspaces() -> None:
+    """List all stored workspaces."""
+    config = ConfigManager()
+    all_ws = config.workspaces
+    current = config.workspace
+
+    if not all_ws:
+        console.print("[dim]No workspaces configured. Run 'fulfil auth login'.[/dim]")
+        return
+
+    for ws in all_ws:
+        if ws == current:
+            console.print(f"  [bold green]*[/bold green] {ws} [dim](current)[/dim]")
+        else:
+            console.print(f"    {ws}")
+
+
+@app.command()
+def use(
+    workspace: str = typer.Argument(help="Workspace to switch to"),
+) -> None:
+    """Switch the active workspace."""
+    config = ConfigManager()
+
+    # Normalize
+    if "." not in workspace:
+        workspace = f"{workspace}.fulfil.io"
+
+    if workspace not in config.workspaces:
+        console.print(f"[red]Workspace '{workspace}' not found.[/red]")
+        console.print("[dim]Run 'fulfil auth login' to add it first.[/dim]")
+        raise typer.Exit(code=3)
+
+    config.workspace = workspace
+    console.print(f"[green]Switched to workspace '{workspace}'.[/green]")

fulfil_cli/cli/commands/completion.py

@@ -0,0 +1,65 @@
+"""Shell completion install command."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+
+def completion_install() -> None:
+    """Install shell completion for the current shell."""
+    shell = _detect_shell()
+    if not shell:
+        console.print("[red]Could not detect shell. Set $SHELL and try again.[/red]")
+        raise typer.Exit(code=2)
+
+    console.print(f"Detected shell: [bold]{shell}[/bold]")
+
+    try:
+        result = subprocess.run(
+            [sys.argv[0], "--show-completion", shell],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            target = _completion_target(shell)
+            console.print(f"[green]Completion installed for {shell}.[/green]")
+            if target:
+                console.print(f"[dim]Wrote to: {target}[/dim]")
+            console.print("[dim]Restart your shell or source your profile to activate.[/dim]")
+        else:
+            console.print(f"[red]Failed to install completion: {result.stderr}[/red]")
+    except Exception as exc:
+        console.print(f"[red]Error: {exc}[/red]")
+        raise typer.Exit(code=1) from None
+
+
+def _detect_shell() -> str | None:
+    """Detect the current shell."""
+    shell_path = os.environ.get("SHELL", "")
+    if "zsh" in shell_path:
+        return "zsh"
+    if "bash" in shell_path:
+        return "bash"
+    if "fish" in shell_path:
+        return "fish"
+    return None
+
+
+def _completion_target(shell: str) -> str | None:
+    """Return the typical completion file path for display."""
+    home = Path.home()
+    if shell == "zsh":
+        return f"{home}/.zfunc/_fulfil"
+    if shell == "bash":
+        return f"{home}/.bash_completions/fulfil.bash"
+    if shell == "fish":
+        return f"{home}/.config/fish/completions/fulfil.fish"
+    return None