kctl-opencloud 0.5.0__tar.gz

kctl_opencloud-0.5.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.pyo
+dist/
+*.egg-info/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/

kctl_opencloud-0.5.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: kctl-opencloud
+Version: 0.5.0
+Summary: Kodemeio OpenCloud CLI — manage OpenCloud file platform
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.5.0
+Requires-Dist: pydantic>=2.10.0
+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'

kctl_opencloud-0.5.0/README.md

@@ -0,0 +1,94 @@
+# kctl-opencloud
+
+Kodemeio OpenCloud CLI — manage users, groups, spaces, and shares on your OpenCloud file storage platform.
+
+## Installation
+
+```bash
+uv tool install kctl-opencloud
+```
+
+Requires `kctl-lib>=0.4.0` (installed automatically).
+
+## Quick Start
+
+```bash
+# Configure a profile
+kctl-opencloud config init
+
+# Check platform health
+kctl-opencloud health check
+
+# View system overview
+kctl-opencloud dashboard show
+
+# List all users
+kctl-opencloud users list
+
+# List spaces with quota info
+kctl-opencloud spaces list
+kctl-opencloud spaces quota <space-id>
+
+# Manage sharing
+kctl-opencloud shares list <space-id> <item-id>
+kctl-opencloud shares create-link <space-id> <item-id>
+```
+
+## Command Groups
+
+| Group | Description | Key Commands |
+|-------|-------------|--------------|
+| `health` | Health checks and monitoring | `check`, `detailed` |
+| `dashboard` | System overview and statistics | `show` |
+| `users` | User management | `list`, `get`, `create`, `update`, `delete` |
+| `groups` | Group management | `list`, `get`, `create`, `update`, `delete`, `add-member`, `remove-member` |
+| `spaces` | Drive and space management | `list`, `get`, `create`, `update`, `delete`, `quota` |
+| `shares` | Sharing and permissions | `list`, `create-link`, `invite`, `delete` |
+| `config` | Profile management | `init`, `add`, `use`, `show`, `validate`, `remove`, `set`, `profiles`, `current` |
+| `doctor` | Diagnostic checks | API connectivity, auth validation |
+
+## Global Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--profile` | `-p` | Config profile name |
+| `--url` | | API URL override |
+| `--token` | | API token override |
+| `--json` | | Output as JSON |
+| `--quiet` | `-q` | Suppress info messages |
+| `--version` | `-V` | Show version and exit |
+
+## Configuration
+
+Config lives in `~/.config/kodemeio/config.yaml` under the `opencloud` service key.
+
+```bash
+# Interactive setup
+kctl-opencloud config init
+
+# Add a named profile
+kctl-opencloud config add --profile production \
+  --url https://opencloud.kodeme.io \
+  --token $OPENCLOUD_TOKEN
+
+# Switch active profile
+kctl-opencloud config use production
+
+# Show current config (secrets masked)
+kctl-opencloud config show
+```
+
+Environment variable overrides:
+- `KCTL_OPENCLOUD_URL` -- API URL
+- `KCTL_OPENCLOUD_TOKEN` -- API token (machine auth key)
+
+## Development
+
+```bash
+cd packages/kctl-opencloud
+uv sync --all-extras
+uv run pytest tests/ -v
+uv run mypy src/
+uv run ruff check src/
+uv build
+```

kctl_opencloud-0.5.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-opencloud"
+version = "0.5.0"
+description = "Kodemeio OpenCloud CLI — manage OpenCloud file platform"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.5.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "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",
+]
+
+[project.scripts]
+kctl-opencloud = "kctl_opencloud.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[project.entry-points."kctl_opencloud.plugins"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_opencloud"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_opencloud-0.5.0/skills/opencloud-admin/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: opencloud-admin
+description: OpenCloud file platform administration via kctl-opencloud CLI (8 groups, ~35 commands). MUST use for ANY kctl-opencloud operation.
+triggers:
+  - kctl-opencloud
+  - opencloud
+  - cloud.kodeme.io
+  - file storage
+  - spaces
+  - drives
+---
+
+# OpenCloud Administration
+
+Use the `kctl-opencloud` CLI for all OpenCloud management tasks.
+
+## Command Groups
+
+| Group | Description |
+|-------|-------------|
+| `health` | Health checks with 5-probe scoring |
+| `dashboard` | System overview and statistics |
+| `config` | Profile and connection management |
+| `users` | User CRUD and search |
+| `groups` | Group management and membership |
+| `spaces` | Drive/space lifecycle and quota |
+| `shares` | Sharing links and permissions |
+| `doctor` | Diagnostic checks |
+
+## Common Patterns
+
+```bash
+# Health
+kctl-opencloud health check
+kctl-opencloud health check --watch
+
+# Users
+kctl-opencloud users list
+kctl-opencloud users list --search "john"
+kctl-opencloud users get <id>
+kctl-opencloud users create user@kodeme.io --name "User Name"
+kctl-opencloud users delete <id> --force
+
+# Groups
+kctl-opencloud groups list
+kctl-opencloud groups create "Team Name"
+kctl-opencloud groups add-member <group-id> <user-id>
+
+# Spaces
+kctl-opencloud spaces list
+kctl-opencloud spaces list --type project
+kctl-opencloud spaces create "Project Name" --description "..."
+kctl-opencloud spaces quota <id>
+
+# Dashboard
+kctl-opencloud dashboard show
+kctl-opencloud dashboard show --json
+
+# Configuration
+kctl-opencloud config init
+kctl-opencloud config show
+kctl-opencloud config test
+```
+
+## JSON Output
+
+All commands support `--json` for machine-readable output:
+```bash
+kctl-opencloud --json users list
+kctl-opencloud --json spaces list
+```

kctl_opencloud-0.5.0/src/kctl_opencloud/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-opencloud: Kodemeio OpenCloud CLI."""
+
+__version__ = "0.5.0"

kctl_opencloud-0.5.0/src/kctl_opencloud/__main__.py

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

kctl_opencloud-0.5.0/src/kctl_opencloud/cli.py

@@ -0,0 +1,124 @@
+"""Main CLI entry point for kctl-opencloud."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from kctl_lib import KctlError, handle_cli_error
+
+from kctl_opencloud import __version__
+from kctl_opencloud.commands.config_cmd import app as config_app
+from kctl_opencloud.commands.dashboard import app as dashboard_app
+from kctl_opencloud.commands.doctor_cmd import app as doctor_app
+from kctl_opencloud.commands.groups import app as groups_app
+from kctl_opencloud.commands.health import app as health_app
+from kctl_opencloud.commands.shares import app as shares_app
+from kctl_opencloud.commands.skill_cmd import app as skill_app
+from kctl_opencloud.commands.spaces import app as spaces_app
+from kctl_opencloud.commands.users import app as users_app
+from kctl_opencloud.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-opencloud {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-opencloud",
+    help="Kodemeio OpenCloud CLI - manage your OpenCloud file platform.",
+    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")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = 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,
+    token: Annotated[str | None, typer.Option("--token", help="API token override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio OpenCloud CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        profile=profile,
+        url_override=url,
+        token_override=token,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-opencloud", __version__)
+
+
+# Register command groups
+app.add_typer(health_app, name="health")
+app.add_typer(dashboard_app, name="dashboard")
+app.add_typer(config_app, name="config")
+app.add_typer(users_app, name="users")
+app.add_typer(groups_app, name="groups")
+app.add_typer(spaces_app, name="spaces")
+app.add_typer(shares_app, name="shares")
+app.add_typer(doctor_app, name="doctor")
+app.add_typer(skill_app, name="skill", hidden=True)
+add_tui_command(app, service_key="opencloud", version=__version__)
+
+
+@app.command("self-update")
+def self_update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-opencloud."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    from kctl_lib.self_update import check_update
+    from kctl_lib.self_update import update as do_update
+
+    latest = check_update("kctl-opencloud", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-opencloud")
+        out.success(f"Updated to {latest}")
+    else:
+        out.success("Already up to date")
+
+
+@app.command()
+def completions(
+    shell: Annotated[str, typer.Argument(help="Shell type: zsh, bash, fish")] = "zsh",
+    install: Annotated[bool, typer.Option("--install", help="Install completions")] = False,
+) -> None:
+    """Generate or install shell completions."""
+    from kctl_lib.completions import get_completion_script, install_completions
+
+    if install:
+        path = install_completions("kctl-opencloud", shell)
+        if path:
+            typer.echo(f"Completions installed to {path}")
+        else:
+            typer.echo(f"Could not install completions for {shell}", err=True)
+            raise typer.Exit(code=1)
+    else:
+        script = get_completion_script("kctl-opencloud", shell)
+        typer.echo(script)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_opencloud-0.5.0/src/kctl_opencloud/commands/config_cmd.py

@@ -0,0 +1,191 @@
+"""Configuration management commands for kctl-opencloud."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_opencloud.core.callbacks import AppContext
+from kctl_opencloud.core.config import (
+    SERVICE_KEY,
+    ServiceConfig,
+    get_default_profile,
+    get_profile_names,
+    get_service_config,
+    remove_profile,
+    resolve_active_profile_name,
+    set_default_profile,
+    set_service_config,
+)
+
+app = typer.Typer(help="Configuration and profile management.")
+
+
+def _mask_token(token: str) -> str:
+    """Mask a token for display."""
+    if not token or len(token) < 8:
+        return "****" if token else ""
+    return token[:4] + "****" + token[-4:]
+
+
+@app.command()
+def init(
+    ctx: typer.Context,
+    url: Annotated[str, typer.Option("--url", help="OpenCloud API URL")] = "",
+    token: Annotated[str, typer.Option("--token", help="Machine auth API key")] = "",
+    profile_name: Annotated[str, typer.Option("--profile", "-p", help="Profile name")] = "default",
+) -> None:
+    """Initialize configuration with API credentials."""
+    c: AppContext = ctx.obj
+
+    if not url:
+        url = typer.prompt("OpenCloud URL", default="https://cloud.kodeme.io")
+    if not token:
+        token = typer.prompt("Machine Auth API Key", hide_input=True)
+
+    svc = ServiceConfig(url=url, token=token)
+    set_service_config(profile_name, svc)
+    set_default_profile(profile_name)
+
+    # Test connection
+    try:
+        from kctl_opencloud.core.client import OpenCloudClient
+
+        client = OpenCloudClient(base_url=url, credential=token)
+        status = client.check_health()
+        if status == 200:
+            c.output.success(f"Connected to {url}")
+        elif status == 0:
+            c.output.warn(f"Could not reach {url} (connection error)")
+        else:
+            c.output.warn(f"Connection returned HTTP {status}")
+    except Exception as e:
+        c.output.warn(f"Could not verify connection: {e}")
+
+    c.output.success(f"Configuration saved to profile '{profile_name}'")
+
+
+@app.command()
+def show(ctx: typer.Context) -> None:
+    """Show current configuration."""
+    c: AppContext = ctx.obj
+    pname = resolve_active_profile_name(c.profile)
+    svc = get_service_config(pname)
+
+    data = {
+        "profile": pname,
+        "service_key": SERVICE_KEY,
+        "url": svc.url or "(not set)",
+        "token": _mask_token(svc.token),
+        "container_name": svc.container_name or "(default)",
+    }
+
+    sections = [
+        (
+            "Configuration",
+            [
+                ("Profile", data["profile"]),
+                ("Service Key", data["service_key"]),
+                ("URL", data["url"]),
+                ("Token", data["token"]),
+                ("Container", data["container_name"]),
+            ],
+        ),
+    ]
+    c.output.detail("OpenCloud Config", sections, data_for_json=data)
+
+
+@app.command()
+def current(ctx: typer.Context) -> None:
+    """Show the active profile name."""
+    c: AppContext = ctx.obj
+    pname = resolve_active_profile_name(c.profile)
+    c.output.text(pname)
+
+
+@app.command("set")
+def set_(
+    ctx: typer.Context,
+    key: Annotated[str, typer.Argument(help="Config key (url, token, container_name)")],
+    value: Annotated[str, typer.Argument(help="Config value")],
+) -> None:
+    """Set a configuration value."""
+    c: AppContext = ctx.obj
+    valid_fields = set(ServiceConfig.model_fields.keys())
+    if key not in valid_fields:
+        c.output.error(f"Invalid key '{key}'. Valid keys: {', '.join(sorted(valid_fields))}")
+        raise typer.Exit(code=1)
+
+    pname = resolve_active_profile_name(c.profile)
+    svc = get_service_config(pname)
+    setattr(svc, key, value)
+    set_service_config(pname, svc)
+    display_value = _mask_token(value) if "token" in key else value
+    c.output.success(f"Set {key} = {display_value}")
+
+
+@app.command()
+def profiles(ctx: typer.Context) -> None:
+    """List all configuration profiles."""
+    c: AppContext = ctx.obj
+    names = get_profile_names()
+    default = get_default_profile()
+
+    rows = []
+    for name in names:
+        svc = get_service_config(name)
+        marker = "*" if name == default else ""
+        rows.append([marker, name, svc.url or "(not set)"])
+
+    c.output.table(
+        "Profiles",
+        [("", "cyan"), ("Name", "green"), ("URL", "white")],
+        rows,
+        data_for_json=[{"name": n, "default": n == default} for n in names],
+    )
+
+
+@app.command("use")
+def use_(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Profile name to activate")],
+) -> None:
+    """Switch to a different profile."""
+    c: AppContext = ctx.obj
+    names = get_profile_names()
+    if name not in names:
+        c.output.error(f"Profile '{name}' not found. Available: {', '.join(names)}")
+        raise typer.Exit(code=1)
+    set_default_profile(name)
+    c.output.success(f"Switched to profile '{name}'")
+
+
+@app.command()
+def remove(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Profile name to remove")],
+) -> None:
+    """Remove a configuration profile."""
+    c: AppContext = ctx.obj
+    remove_profile(name)
+    c.output.success(f"Removed profile '{name}'")
+
+
+@app.command()
+def test(ctx: typer.Context) -> None:
+    """Test the current connection."""
+    c: AppContext = ctx.obj
+    try:
+        status = c.client.check_health()
+        if status == 200:
+            c.output.success("Connection OK")
+            version = c.client.get_version()
+            if version:
+                c.output.info(f"OpenCloud {version}")
+        else:
+            c.output.error(f"Connection failed (HTTP {status})")
+            raise typer.Exit(code=1)
+    except Exception as e:
+        c.output.error(f"Connection failed: {e}")
+        raise typer.Exit(code=1)

kctl_opencloud-0.5.0/src/kctl_opencloud/commands/dashboard.py

@@ -0,0 +1,80 @@
+"""Dashboard commands for kctl-opencloud."""
+
+from __future__ import annotations
+
+import time
+from typing import Annotated, Any
+
+import typer
+from kctl_lib.exceptions import AuthenticationError, ConfigError
+
+from kctl_opencloud.core.callbacks import AppContext
+
+app = typer.Typer(help="System overview and statistics.")
+
+
+def _fetch_dashboard(c: AppContext) -> dict[str, Any]:
+    """Fetch dashboard data."""
+    client = c.client
+    data: dict[str, Any] = {}
+
+    # Version
+    data["version"] = client.get_version() or "unknown"
+
+    # Resource counts
+    for resource, endpoint in [("users", "users"), ("groups", "groups"), ("spaces", "drives")]:
+        try:
+            result = client.get(endpoint)
+            data[resource] = len(result.get("value", []))
+        except (AuthenticationError, ConfigError):
+            raise
+        except Exception:
+            data[resource] = 0
+
+    return data
+
+
+def _display_dashboard(c: AppContext, data: dict[str, Any]) -> None:
+    """Display dashboard."""
+    out = c.output
+
+    if c.json_mode:
+        out.raw_json(data)
+        return
+
+    out.header("OpenCloud Dashboard")
+    out.kv("URL", c.client.root_url)
+    out.kv("Version", data["version"])
+    out.text("")
+    out.kv("Users", str(data.get("users", 0)))
+    out.kv("Groups", str(data.get("groups", 0)))
+    out.kv("Spaces", str(data.get("spaces", 0)))
+
+
+@app.callback(invoke_without_command=True)
+def show(
+    ctx: typer.Context,
+    watch: Annotated[bool, typer.Option("--watch", "-w", help="Continuous monitoring")] = False,
+    interval: Annotated[int, typer.Option("--interval", "-i", help="Watch interval")] = 10,
+    compact: Annotated[bool, typer.Option("--compact", "-c", help="Compact output")] = False,
+) -> None:
+    """Show system overview."""
+    c: AppContext = ctx.obj
+
+    if watch:
+        try:
+            while True:
+                data = _fetch_dashboard(c)
+                if compact:
+                    c.output.text(f"Users: {data['users']} | Groups: {data['groups']} | Spaces: {data['spaces']}")
+                else:
+                    _display_dashboard(c, data)
+                time.sleep(interval)
+        except KeyboardInterrupt:
+            pass
+    else:
+        data = _fetch_dashboard(c)
+        if compact:
+            c.output.text(f"Users: {data['users']} | Groups: {data['groups']} | Spaces: {data['spaces']}")
+        else:
+            _display_dashboard(c, data)