ocmo-cli 0.8.19__py3-none-any.whl

ocmo_cli/main.py

@@ -0,0 +1,241 @@
+"""Root CLI entry point.
+
+All heavy imports (SDK, yaml, httpx) are deferred into command functions so
+that `ocmo --help` returns within the 200 ms budget on a warm cache.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import click
+
+from ._click_groups import LazyGroup
+from ._client import OcmoCtx
+from ._command_registry import HAND_WRITTEN_SHORT_HELP
+from ._lazy_mixin import ClickLazyMixin
+from ._output import _OUTPUT_FORMATS
+
+
+def _validate_output_global(ctx: click.Context, param: click.Parameter, value: str | None) -> str | None:
+    if value is None:
+        return value
+    if value in _OUTPUT_FORMATS or value.startswith("jsonpath="):
+        return value
+    valid = ", ".join(_OUTPUT_FORMATS)
+    raise click.BadParameter(
+        f"{value!r} is not a valid format. Valid values: {valid}, or jsonpath=<expr>.",
+        ctx=ctx,
+        param=param,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Global flags — attached to every invocation via callback
+# ---------------------------------------------------------------------------
+
+CONTEXT_SETTINGS = dict(help_option_names=["--help", "-h"], max_content_width=120)
+
+
+@click.group(context_settings=CONTEXT_SETTINGS, invoke_without_command=True)
+@click.version_option(package_name="ocmo-cli", prog_name="ocmo")
+@click.option(
+    "-n",
+    "--namespace",
+    envvar="OCMO_NAMESPACE",
+    default=None,
+    metavar="NS",
+    help="Namespace (overrides config and OCMO_NAMESPACE).",
+)
+@click.option(
+    "-o",
+    "--output",
+    "output_fmt",
+    default=None,
+    metavar="FORMAT",
+    callback=lambda ctx, p, v: _validate_output_global(ctx, p, v),
+    is_eager=False,
+    help=(
+        "Output format: table, json, yaml, name, path, raw, or jsonpath=<expr>. "
+        "Default: table on TTY, yaml otherwise."
+    ),
+)
+@click.option(
+    "--dry-run", is_flag=True, default=False, help="Print what would be done without contacting mutating endpoints."
+)
+@click.option("-v", "--verbose", is_flag=True, default=False, help="Raise log level.")
+@click.option("-q", "--quiet", is_flag=True, default=False, help="Suppress non-error stderr output.")
+@click.option("--yes", "-y", is_flag=True, default=False, help="Skip confirmation prompts.")
+@click.option("--no-color", is_flag=True, default=False, envvar="OCMO_NO_COLOR", help="Disable ANSI colour.")
+@click.option(
+    "--skip-version-check",
+    is_flag=True,
+    default=False,
+    envvar="OCMO_SKIP_VERSION_CHECK",
+    help="Skip CLI/SDK/server version compatibility check.",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    namespace: str | None,
+    output_fmt: str | None,
+    dry_run: bool,
+    verbose: bool,
+    quiet: bool,
+    yes: bool,
+    no_color: bool,
+    skip_version_check: bool,
+) -> None:
+    """ocmo — configuration management CLI.
+
+    \b
+    Examples:
+      ocmo config set server https://ocmo.example.com
+      ocmo auth login
+      ocmo -n prod ls
+      ocmo -n prod get item app/web
+      ocmo -n prod resolve app/web --cast json
+      ocmo -n prod apply -f config.yaml app/web/main
+    """
+    if no_color:
+        os.environ["OCMO_NO_COLOR"] = "1"
+
+    ctx.ensure_object(dict)
+    ctx.obj = OcmoCtx(
+        namespace=namespace,
+        output=output_fmt,
+        dry_run=dry_run,
+        verbose=verbose,
+        quiet=quiet,
+        yes=yes,
+        skip_version_check=skip_version_check,
+        no_color=no_color,
+    )
+
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+# ---------------------------------------------------------------------------
+# Hand-written command modules
+# ---------------------------------------------------------------------------
+
+
+def _lazy_cmd(
+    name: str,
+    module: str,
+    attr: str,
+    short_help: str,
+    *,
+    hidden: bool = False,
+) -> click.Command:
+    """Return a placeholder that imports and delegates on first invocation."""
+
+    class LazyCommand(ClickLazyMixin, click.Command):
+        """A stub that replaces itself with the real command on first use."""
+
+        def __init__(self) -> None:
+            super().__init__(name)
+            self.short_help = short_help
+            self.hidden = hidden
+
+        def _lazy_target(self) -> click.Command:
+            return self._real()
+
+        def _real(self) -> click.Command:
+            import importlib
+
+            mod = importlib.import_module(f".commands.{module}", package="ocmo_cli")
+            cmd = getattr(mod, attr)
+            assert isinstance(cmd, click.Command)
+            return cmd
+
+        def get_params(self, ctx: click.Context) -> list[click.Parameter]:
+            return self._real().get_params(ctx)
+
+        def get_help(self, ctx: click.Context) -> str:
+            return self._real().get_help(ctx)
+
+        def get_short_help_str(self, limit: int = 150) -> str:
+            text = self.short_help or ""
+            if limit and len(text) > limit:
+                return text[: limit - 3] + "..."
+            return text
+
+        def main(  # type: ignore[override]
+            self,
+            args: list[str] | None = None,
+            prog_name: str | None = None,
+            complete_var: str | None = None,
+            standalone_mode: bool = True,
+            **extra: Any,
+        ) -> Any:
+            return self._real().main(
+                args,
+                prog_name=prog_name,
+                complete_var=complete_var,
+                standalone_mode=standalone_mode,
+                **extra,
+            )
+
+    return LazyCommand()
+
+
+def _register_hand_written() -> None:
+    # Register lazy stubs — actual imports happen only when the command runs.
+    for cli_name, (module, attr, short_help) in HAND_WRITTEN_SHORT_HELP.items():
+        cli.add_command(_lazy_cmd(cli_name, module, attr, short_help), name=cli_name)
+
+
+# ---------------------------------------------------------------------------
+# Generated command groups (built from commands.yaml on first use)
+# ---------------------------------------------------------------------------
+
+
+def _build_generated_action(action: str) -> click.Group:
+    from .commands.generated import build_action_group
+
+    return build_action_group(action)
+
+
+def _register_generated() -> None:
+    from ._generated_registry import action_help, generated_action_names
+
+    # Hand-written commands take precedence — skip generated groups that share a name
+    existing_names = set(cli.commands or {})
+    for action in generated_action_names():
+        if action not in existing_names:
+
+            def _build(action_name: str = action) -> click.Group:
+                return _build_generated_action(action_name)
+
+            cli.add_command(
+                LazyGroup(
+                    action,
+                    help=action_help(action),
+                    build_fn=_build,
+                ),
+                name=action,
+            )
+
+    cli.add_command(
+        _lazy_cmd(
+            "api",
+            "api",
+            "api_cmd",
+            "Invoke any API operation directly by operation_id.",
+            hidden=True,
+        ),
+        name="api",
+    )
+
+    from .commands.gp_move import register_gp_move_command
+    from .commands.item_relocate import register_item_relocate_commands
+
+    register_item_relocate_commands(cli)
+    register_gp_move_command(cli)
+
+
+_register_hand_written()
+_register_generated()

ocmo_cli/output_formats.yaml

@@ -0,0 +1,295 @@
+# Output format manifest — source of truth for OCMO CLI -o/--output behavior.
+#
+# Command keys use space-separated paths: "get namespace", "ls", "resolve".
+# Generated commands use "{action} {resource}" (canonical resource name).
+#
+# Profile ``supported_formats`` and defaults merge into each command entry.
+# Per-command ``table`` / ``wide`` / ``raw`` blocks configure column layout.
+
+profiles:
+  list_wide:
+    supported_formats: [table, wide, json, yaml, name]
+    default_tty: table
+    default_non_tty: yaml
+    name_field: name
+
+  list:
+    supported_formats: [table, json, yaml, name]
+    default_tty: table
+    default_non_tty: yaml
+    name_field: name
+
+  list_versions:
+    supported_formats: [table, wide, json, yaml, name]
+    default_tty: table
+    default_non_tty: yaml
+    name_field: version
+
+  document:
+    supported_formats: [raw, json, yaml, name]
+    default: raw
+    name_field: path
+
+  ls:
+    supported_formats: [table, wide, json, yaml, name, path]
+    default_tty: table
+    default_non_tty: yaml
+    name_field: path
+
+  resolve:
+    supported_formats: [raw, json, yaml, name]
+    default: raw
+    name_field: name
+
+  can_i:
+    supported_formats: [table, json, yaml]
+    default_tty: table
+    default_non_tty: yaml
+
+  schema:
+    supported_formats: [table, json, yaml]
+    default_tty: yaml
+    default_non_tty: yaml
+
+commands:
+  # ── Hand-written ──────────────────────────────────────────────────────────
+
+  ls:
+    profile: ls
+    table:
+      fields: [type, path]
+    wide:
+      fields: [permissions, versions, author, created, updated, type, path]
+
+  resolve:
+    profile: resolve
+    raw:
+      mode: metadata_and_data
+      hide_null_values: true
+
+  can-i:
+    profile: can_i
+
+  whoami:
+    profile: can_i
+    table:
+      fields: "*"
+
+  api-health:
+    profile: list
+    name_field: status
+
+  schema:
+    supported_formats: [json, yaml]
+    default_tty: yaml
+    default_non_tty: yaml
+
+  auth status:
+    profile: schema
+
+  edit config:
+    profile: document
+
+  edit template:
+    profile: document
+
+  edit secret:
+    profile: document
+
+  edit resolver:
+    profile: document
+
+  # ── Generated: get ────────────────────────────────────────────────────────
+
+  get namespace:
+    profile: list_wide
+    table:
+      fields: [name, description]
+    wide:
+      fields: [name, description, permissions_tag, webhooks_tag, git_sync_tag, created_at, updated_at]
+
+  get globalpermission:
+    profile: list_wide
+    name_field: id
+    table:
+      fields: [id, namespace, position]
+    wide:
+      fields: [id, namespace, position, read, write, delete, audit]
+
+  get lock:
+    profile: list_wide
+    name_field: path
+    table:
+      fields: [path, reason, locked_by]
+    wide:
+      fields: "*"
+
+  get audit:
+    profile: list_wide
+    name_field: id
+    table:
+      fields: [occurred_at, id, operation, object_id]
+    wide:
+      fields: [occurred_at, id, operation, object_id, auth_email, object_type, object_version, error]
+
+  get cast:
+    profile: schema
+
+  get cast list:
+    profile: list
+    name_field: format
+    table:
+      fields: [format]
+
+  get version:
+    profile: list_versions
+    table:
+      fields: [version, tags, updated_at]
+    wide:
+      fields: "*"
+
+  get item:
+    profile: document
+
+  get item list:
+    profile: list
+    name_field: path
+    table:
+      fields: [node_type, path, name]
+
+  # ── Generated: create ─────────────────────────────────────────────────────
+
+  create namespace:
+    profile: list
+
+  create globalpermission:
+    profile: document
+    name_field: id
+
+  create config:
+    profile: document
+
+  create template:
+    profile: document
+
+  create secret:
+    profile: document
+
+  create resolver:
+    profile: document
+
+  create lock:
+    profile: list
+    name_field: path
+
+  # ── Generated: update / delete / move / copy / tag ─────────────────────────
+
+  update namespace:
+    profile: list
+
+  update globalpermission:
+    profile: document
+    name_field: id
+
+  update config:
+    profile: document
+
+  update template:
+    profile: document
+
+  update secret:
+    profile: document
+
+  update resolver:
+    profile: document
+
+  update lock:
+    profile: list
+    name_field: path
+
+  delete namespace:
+    profile: list
+    name_field: namespace
+
+  delete item:
+    profile: list
+    name_field: path
+    supported_formats: [table, json, yaml, name, path]
+    table:
+      fields: [type, version, path]
+
+  delete globalpermission:
+    profile: list
+    name_field: id
+
+  delete lock:
+    profile: list
+    name_field: path
+
+  tag item:
+    profile: list_versions
+    table:
+      fields: [version, tags, updated_at]
+    wide:
+      fields: "*"
+
+  untag item:
+    profile: list_versions
+    table:
+      fields: [version, tags, updated_at]
+    wide:
+      fields: "*"
+
+  propagate config:
+    profile: list
+    name_field: path
+
+  search tree:
+    profile: list
+    name_field: path
+
+  resolve-series audit:
+    supported_formats: [chart, json, yaml]
+    default_tty: chart
+    default_non_tty: yaml
+
+  resolve parameters:
+    supported_formats: [table, json, yaml]
+    default_tty: table
+    default_non_tty: yaml
+    table:
+      fields: [name, type, value, resolved_value, description, transformers]
+
+  resolve draft:
+    profile: resolve
+
+  # Fallback for generated commands not listed explicitly.
+  _generated_defaults:
+    get:
+      profile: list_wide
+    create:
+      profile: list
+    update:
+      profile: list
+    delete:
+      profile: list
+    move:
+      profile: list
+    copy:
+      profile: list
+    tag:
+      profile: list
+    untag:
+      profile: list
+    rotate:
+      profile: list
+    propagate:
+      profile: list
+    search:
+      profile: list_wide
+    timeline:
+      profile: list_wide
+    resolve-series:
+      profile: list_wide
+    resolve:
+      profile: resolve

ocmo_cli-0.8.19.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: ocmo-cli
+Version: 0.8.19
+Summary: Command-line interface for the OCMO configuration service
+Project-URL: Homepage, https://github.com/ocmo-oss/ocmo
+Project-URL: Repository, https://github.com/ocmo-oss/ocmo
+Project-URL: Documentation, https://github.com/ocmo-oss/ocmo/tree/main/cli
+Author: OCMO OSS Contributors
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: cli,configuration,devops,yaml
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: click<9,>=8.1
+Requires-Dist: ocmo-sdk<0.9,>=0.8.19
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# ocmo-cli
+
+Command-line interface for the OCMO configuration service. A thin shell over
+[`ocmo-sdk`](https://pypi.org/project/ocmo-sdk/) with a `kubectl`-shaped verb/noun grammar. The CLI
+contains no API protocol logic of its own.
+
+**Distribution:** PyPI name `ocmo-cli` · **Python:** 3.11+ · **License:** Apache-2.0
+
+**Pre-1.0.0:** Pin `ocmo-cli` and `ocmo-sdk` to the same release as your OCMO API server.
+
+---
+
+## Installation
+
+Published package:
+
+```bash
+uv tool install ocmo-cli
+# or
+pipx install ocmo-cli
+```
+
+Monorepo development (from repository root):
+
+```bash
+uv sync --all-packages
+uv run ocmo --help
+```
+
+---
+
+## Quick start
+
+```bash
+# Point at your server (saved to ~/.config/ocmo/config.yaml)
+ocmo config set server https://ocmo.example.com
+ocmo config set namespace prod
+
+# Authenticate
+ocmo auth login
+
+# Use it
+ocmo -n prod get config app/web
+ocmo -n prod resolve app/web --cast json
+ocmo -n prod ls tree app/
+```
+
+---
+
+## Configuration
+
+Precedence (same model as `kubectl`):
+
+```text
+command flag > OCMO_* env var > current context in ~/.config/ocmo/config.yaml > built-in default
+```
+
+Manage contexts:
+
+```bash
+ocmo config get-contexts
+ocmo config use-context prod
+ocmo config set server https://ocmo.example.com
+ocmo config view
+```
+
+---
+
+## Output formats
+
+`-o, --output` accepts: `table` (default on TTY), `wide`, `json`, `yaml`, `name`, `raw`,
+`jsonpath=<expr>`.
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Generic runtime failure |
+| 2 | Usage error |
+| 3 | Not found (404) |
+| 4 | Auth / permission failure (401, 403) |
+| 5 | Conflict (409) |
+| 6 | Path locked (423) |
+| 7 | Validation failure (422, 413) |
+| 8 | Hook execution failure |
+| 9 | Import/export verification failure |
+| 130 | Interrupted |
+
+---
+
+## Development
+
+From repository root (workspace includes CLI and SDK):
+
+```bash
+uv sync --all-packages
+uv run pytest cli/tests -q
+uv run ruff check cli/
+uv run mypy cli/ocmo_cli
+```
+
+Regenerate the command tree from the SDK operation map:
+
+```bash
+cd cli
+uv run python scripts/generate_commands.py --write
+```
+
+Integration smoke tests (live API):
+
+```bash
+OCMO_RUN_INTEGRATION=1 uv run pytest cli/tests/test_smoke_integration.py -v
+```
+
+---
+
+## Architecture notes
+
+### Command surface
+
+Generated operations are registered at import time from committed `commands.yaml` (produced from
+`sdk/operations.yaml`). CI fails if the file drifts from the spec. Hand-written commands live in
+`ocmo_cli/commands/`.
+
+### Framework
+
+Built on **click** (not typer) for fast cold start, dynamic command registration, and programmatic
+`ocmo api` escape hatch.
+
+---
+
+## Related components
+
+- SDK: [../sdk/README.md](../sdk/README.md)
+- API: [../api/README.md](../api/README.md)
+- Integration guides: [../docs/how-to/README.md](../docs/how-to/README.md) · [../docs/reference/cli.md](../docs/reference/cli.md)
+- Monorepo overview: [../README.md](../README.md)