ocmo-cli 0.8.19__py3-none-any.whl

ocmo_cli/commands/resolve_draft.py

@@ -0,0 +1,102 @@
+"""ocmo resolve draft — resolve unsaved config YAML without persisting it."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from .._address import parse_simple_address_or_exit, reject_version
+from .._client import OcmoCtx
+from .._errors import sdk_command
+from .._options import namespace_option
+from .._resolve_draft import call_resolve_draft
+from .._resolve_options import resolve_options
+
+_DRAFT_HELP = """\
+Resolve unsaved draft YAML at ADDRESS without persisting it.
+
+Uses the same output, cast, parameter, filesystem, and hook options as
+``ocmo resolve``. Draft content is read from ``-f/--file`` (or stdin via ``-``).
+
+\b
+Examples:
+  ocmo -n prod resolve draft app/web -f draft.yaml
+  ocmo -n prod resolve draft app/web -f - --cast json < draft.yaml
+  ocmo -n prod resolve draft app/web -f draft.yaml --trace-only -o yaml
+"""
+
+
+@click.command("draft", help=_DRAFT_HELP)
+@click.argument("address")
+@namespace_option()
+@resolve_options(include_version=False, file_required=True)
+@click.pass_obj
+@sdk_command
+def resolve_draft_cmd(
+    ctx: OcmoCtx,
+    address: str,
+    namespace: str | None,
+    output_fmt: str | None,
+    cast: str | None,
+    params: tuple[str, ...],
+    cast_options: tuple[str, ...],
+    output_file: str | None,
+    output_dir: str | None,
+    rewrite: bool,
+    skip_existing: bool,
+    trace_only: bool,
+    prop_path: str | None,
+    exec_hooks: bool,
+    hook_timeout: int,
+    trust_hooks_sha: str | None,
+    print_hooks: bool,
+    file_path: str,
+) -> None:
+    from .resolve import _parse_kv_args, _print_hooks, run_resolve_pipeline
+
+    path, version = parse_simple_address_or_exit(address)
+    reject_version(version, command="resolve draft")
+
+    content = sys.stdin.read() if file_path == "-" else Path(file_path).read_text()
+
+    params_dict = _parse_kv_args(params)
+    cast_options_dict = _parse_kv_args(cast_options)
+
+    view = ctx.namespace_view(namespace)
+    ns = ctx.require_namespace(namespace)
+
+    if print_hooks:
+        trace_only = True
+
+    result = call_resolve_draft(
+        view,
+        path,
+        content=content,
+        cast=cast,
+        trace_only=trace_only,
+        params=params_dict or None,
+        cast_options=cast_options_dict or None,
+    )
+
+    if print_hooks:
+        _print_hooks(result)
+        return
+
+    run_resolve_pipeline(
+        ctx,
+        result,
+        path=path,
+        ns=ns,
+        output_fmt=output_fmt,
+        output_file=output_file,
+        output_dir=output_dir,
+        rewrite=rewrite,
+        skip_existing=skip_existing,
+        trace_only=trace_only,
+        prop_path=prop_path,
+        exec_hooks=exec_hooks,
+        hook_timeout=hook_timeout,
+        trust_hooks_sha=trust_hooks_sha,
+    )

ocmo_cli/commands/resolve_parameters.py

@@ -0,0 +1,65 @@
+"""ocmo resolve parameters — effective parameter values for a config."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from .._address import parse_address_or_exit
+from .._client import OcmoCtx
+from .._errors import sdk_command
+from .._options import namespace_option, output_option
+from .._output_manifest import emit_command_output
+from .._resolve_parameters_output import filter_parameters_data
+
+_COMMAND_KEY = "resolve parameters"
+
+_PARAMETER_TYPE_CHOICES = ("projected", "dynamic", "secret")
+
+_PARAMETERS_HELP = """\
+Show effective parameter values for a config (debug).
+
+\b
+Examples:
+  ocmo -n prod resolve parameters app/web
+  ocmo -n prod resolve parameters app/web@stable -o yaml
+  ocmo -n prod resolve parameters app/web --type secret
+  ocmo -n prod resolve parameters app/web --type projected --type dynamic
+"""
+
+
+@click.command("parameters", help=_PARAMETERS_HELP)
+@click.argument("address")
+@namespace_option()
+@output_option(_COMMAND_KEY)
+@click.option("--version", "-V", "version_flag", default=None, help="Version / tag to resolve.")
+@click.option(
+    "--type",
+    "param_types",
+    multiple=True,
+    type=click.Choice(_PARAMETER_TYPE_CHOICES, case_sensitive=False),
+    help="Filter parameters by type (repeatable).",
+)
+@click.pass_obj
+@sdk_command
+def resolve_parameters_cmd(
+    ctx: OcmoCtx,
+    address: str,
+    namespace: str | None,
+    output_fmt: str | None,
+    version_flag: str | None,
+    param_types: tuple[str, ...],
+) -> None:
+    path, version = parse_address_or_exit(address, version_flag=version_flag)
+
+    view = ctx.namespace_view(namespace)
+
+    kwargs: dict[str, Any] = {}
+    if version:
+        kwargs["version"] = version
+
+    result = view.resolve_parameters(path, **kwargs)
+    data = filter_parameters_data(result, param_types)
+
+    emit_command_output(_COMMAND_KEY, data, output_fmt, ctx_fmt=ctx.output)

ocmo_cli/commands/resolve_series.py

@@ -0,0 +1,109 @@
+"""ocmo resolve-series audit — time-bucketed resolve statistics."""
+
+from __future__ import annotations
+
+import click
+
+from .._audit_item import resolve_audit_item
+from .._client import OcmoCtx
+from .._errors import sdk_command
+from .._exit import USAGE_ERROR
+from .._options import namespace_option, output_option
+from .._output import emit, err
+from .._output_manifest import emit_command_output, get_command_spec, resolve_effective_format
+from .._resolve_series import resolve_bucket_seconds, resolve_time_range, series_to_dict
+from .._resolve_series_chart import print_resolve_series_chart
+
+_COMMAND_KEY = "resolve-series audit"
+
+_AUDIT_HELP = """\
+Show time-bucketed direct, nested, and error resolve counts for a tree item.
+
+\b
+Examples:
+  ocmo -n prod resolve-series audit app/web
+  ocmo -n prod resolve-series audit app/web -o json
+  ocmo -n prod resolve-series audit app/web --from 2026-07-01T00:00:00Z
+"""
+
+
+@click.group("resolve-series", help="Resolve statistics over time.")
+def resolve_series_group() -> None:
+    """Resolve-series commands."""
+
+
+@resolve_series_group.command("audit", help=_AUDIT_HELP)
+@click.argument("address")
+@click.option(
+    "--from",
+    "from_value",
+    default=None,
+    metavar="ISO",
+    help="Range start (ISO-8601 UTC). Default: 30 days before --to.",
+)
+@click.option(
+    "--to",
+    "to_value",
+    default=None,
+    metavar="ISO",
+    help="Range end (ISO-8601 UTC). Default: now.",
+)
+@click.option(
+    "--bucket-seconds",
+    type=int,
+    default=None,
+    help="Bucket size in seconds (minimum 1800). Default: auto from range.",
+)
+@namespace_option()
+@output_option(_COMMAND_KEY)
+@click.pass_obj
+@sdk_command
+def resolve_series_audit_cmd(
+    ctx: OcmoCtx,
+    address: str,
+    from_value: str | None,
+    to_value: str | None,
+    bucket_seconds: int | None,
+    namespace: str | None,
+    output_fmt: str | None,
+) -> None:
+    view, path, node_type = resolve_audit_item(
+        ctx,
+        address,
+        namespace,
+        command="resolve-series audit",
+    )
+
+    try:
+        start, end = resolve_time_range(from_value, to_value)
+        bucket = resolve_bucket_seconds(start, end, override=bucket_seconds)
+    except ValueError as exc:
+        err(str(exc))
+        raise SystemExit(USAGE_ERROR) from exc
+
+    result = view.namespace_audit_resolve_series(
+        object_id=path,
+        object_type=node_type,
+        from_=start,
+        to=end,
+        bucket_seconds=bucket,
+    )
+    data = series_to_dict(result)
+
+    spec = get_command_spec(_COMMAND_KEY)
+    effective_fmt = resolve_effective_format(output_fmt, ctx.output, spec)
+
+    if effective_fmt == "chart":
+        print_resolve_series_chart(
+            data,
+            node_type=node_type,
+            range_start=start,
+            range_end=end,
+        )
+        return
+
+    if effective_fmt in ("json", "yaml"):
+        emit(data, effective_fmt)
+        return
+
+    emit_command_output(_COMMAND_KEY, data, output_fmt, ctx_fmt=ctx.output)

ocmo_cli/commands/schema.py

@@ -0,0 +1,112 @@
+"""ocmo schema — render JSON Schemas for OCMO metadata and resource configuration."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+import click
+
+from .._client import OcmoCtx
+from .._errors import sdk_command
+from .._options import namespace_option, output_option
+from .._output import as_dict
+from .._output_manifest import emit_command_output
+
+_VALID_RESOURCES = "ocmo, config, resolver"
+
+
+@dataclass(frozen=True)
+class _SchemaSpec:
+    aliases: tuple[str, ...]
+    requires_address: bool
+    forbids_address: bool
+    usage_error: str
+    fetch: Callable[[OcmoCtx, str | None, str | None], Any]
+
+
+def _fetch_ocmo_schema(ctx: OcmoCtx, _namespace: str | None, _address: str | None) -> Any:
+    return ctx.client().get_config_metadata_schema()  # type: ignore[no-untyped-call]
+
+
+def _fetch_resolver_schema(ctx: OcmoCtx, _namespace: str | None, _address: str | None) -> Any:
+    return ctx.client().get_resolver_configuration_schema()  # type: ignore[no-untyped-call]
+
+
+def _fetch_config_schema(ctx: OcmoCtx, namespace: str | None, address: str | None) -> Any:
+    if not address:
+        raise click.UsageError(
+            "ADDRESS is required for RESOURCE 'config'. " "Use: ocmo -n <namespace> schema config <path>"
+        )
+    return ctx.namespace_view(namespace).get_config_data_schema(path=address)
+
+
+_SCHEMA_DISPATCH: dict[str, _SchemaSpec] = {
+    "ocmo": _SchemaSpec(
+        aliases=("ocmo",),
+        requires_address=False,
+        forbids_address=True,
+        usage_error="ADDRESS is not used with RESOURCE 'ocmo'. Use: ocmo schema ocmo",
+        fetch=_fetch_ocmo_schema,
+    ),
+    "config": _SchemaSpec(
+        aliases=("config", "cfg", "configs"),
+        requires_address=True,
+        forbids_address=False,
+        usage_error="",
+        fetch=_fetch_config_schema,
+    ),
+    "resolver": _SchemaSpec(
+        aliases=("resolver", "rsv", "resolvers"),
+        requires_address=False,
+        forbids_address=True,
+        usage_error="ADDRESS is not used with RESOURCE 'resolver'. Use: ocmo schema resolver",
+        fetch=_fetch_resolver_schema,
+    ),
+}
+
+_SCHEMA_LOOKUP: dict[str, _SchemaSpec] = {alias: spec for spec in _SCHEMA_DISPATCH.values() for alias in spec.aliases}
+
+
+@click.command("schema", help="Render the JSON Schema for a resource type.")
+@click.argument("resource_type", metavar="RESOURCE", required=False)
+@click.argument("address", required=False)
+@namespace_option()
+@output_option("schema")
+@click.pass_obj
+@sdk_command
+def schema_cmd(
+    ctx: OcmoCtx,
+    resource_type: str | None,
+    address: str | None,
+    namespace: str | None,
+    output_fmt: str | None,
+) -> None:
+    """Render the JSON Schema for a resource type.
+
+    \b
+    Resource types:
+      ocmo               — ``_ocmo`` metadata block schema
+      config / cfg       — config data schema (requires ADDRESS and -n)
+      resolver / rsv     — resolver configuration schema
+
+    \b
+    Examples:
+      ocmo schema ocmo                      # _ocmo block schema
+      ocmo -n prod schema config app/web      # data schema for a specific config
+      ocmo schema resolver                  # resolver configuration schema
+    """
+    if not resource_type:
+        raise click.UsageError(f"RESOURCE type is required. Valid types: {_VALID_RESOURCES}")
+
+    spec = _SCHEMA_LOOKUP.get(resource_type.lower())
+    if spec is None:
+        raise click.UsageError(f"Unknown resource type {resource_type!r}. Valid: {_VALID_RESOURCES}")
+
+    if spec.forbids_address and address:
+        raise click.UsageError(spec.usage_error)
+
+    schema = spec.fetch(ctx, namespace, address)
+    data = as_dict(schema)
+    emit_command_output("schema", data, output_fmt, ctx_fmt=ctx.output)

ocmo_cli/commands/timeline.py

@@ -0,0 +1,135 @@
+"""ocmo timeline audit — item modification history as human-readable notes."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any
+
+import click
+
+from .._audit_item import resolve_audit_item
+from .._client import OcmoCtx
+from .._errors import sdk_command
+from .._exit import USAGE_ERROR
+from .._options import namespace_option
+from .._output import as_dict, err, format_datetime
+
+if TYPE_CHECKING:
+    from ocmo import NamespaceView
+
+_TIMELINE_PAGE_SIZE = 100
+
+_AUDIT_HELP = """\
+Show modification history for a tree item as human-readable notes.
+
+\b
+Examples:
+  ocmo -n prod timeline audit app/web
+  ocmo -n prod timeline audit app/web --search stable
+  ocmo -n prod timeline audit app/web --limit 10
+"""
+
+
+def _reject_output_format(ctx: OcmoCtx) -> None:
+    if ctx.output:
+        raise click.UsageError("timeline audit does not support -o/--output or OCMO_OUTPUT for this command.")
+
+
+def _fetch_timeline_entries(
+    view: NamespaceView,
+    *,
+    path: str,
+    node_type: str,
+    search: str | None,
+    limit: int | None = None,
+) -> list[Any]:
+    entries: list[Any] = []
+    offset = 0
+    while True:
+        if limit is not None:
+            remaining = limit - len(entries)
+            if remaining <= 0:
+                break
+            page_limit = min(_TIMELINE_PAGE_SIZE, remaining)
+        else:
+            page_limit = _TIMELINE_PAGE_SIZE
+
+        page = view.namespace_audit_timeline(
+            object_id=path,
+            object_type=node_type,
+            search=search,
+            limit=page_limit,
+            offset=offset,
+        )
+        items = list(getattr(page, "items", []) or [])
+        entries.extend(items)
+        if limit is not None and len(entries) >= limit:
+            return entries[:limit]
+        total = int(getattr(page, "count", len(entries)))
+        if not items or offset + len(items) >= total:
+            break
+        offset += len(items)
+    return entries
+
+
+def _entry_message(entry: Any) -> tuple[str, str]:
+    data = as_dict(entry)
+    occurred_at = format_datetime(data.get("occurred_at"))
+    message = str(data.get("message") or "").strip()
+    return occurred_at, message
+
+
+@click.group("timeline", help="Item-scoped audit timelines.")
+def timeline_group() -> None:
+    """Timeline commands."""
+
+
+@timeline_group.command("audit", help=_AUDIT_HELP)
+@click.argument("address")
+@click.option("--search", default=None, help="Filter notes (matches audit timeline search).")
+@click.option("--limit", type=int, default=None, help="Maximum number of timeline events to show.")
+@namespace_option()
+@click.pass_obj
+@sdk_command
+def timeline_audit_cmd(
+    ctx: OcmoCtx,
+    address: str,
+    search: str | None,
+    limit: int | None,
+    namespace: str | None,
+) -> None:
+    _reject_output_format(ctx)
+
+    view, path, node_type = resolve_audit_item(
+        ctx,
+        address,
+        namespace,
+        command="timeline audit",
+        allow_version_flag=True,
+    )
+
+    if limit is not None and limit < 1:
+        err("--limit must be a positive integer.")
+        raise SystemExit(USAGE_ERROR)
+
+    entries = _fetch_timeline_entries(
+        view,
+        path=path,
+        node_type=node_type,
+        search=search,
+        limit=limit,
+    )
+
+    if not entries:
+        if sys.stdout.isatty():
+            print("No audit events found.")
+        return
+
+    for entry in entries:
+        occurred_at, message = _entry_message(entry)
+        if occurred_at and message:
+            print(f"{occurred_at}  {message}")
+        elif message:
+            print(message)
+        elif occurred_at:
+            print(occurred_at)

ocmo_cli/commands/version_cmd.py

@@ -0,0 +1,102 @@
+"""ocmo version — print CLI, SDK, and server versions with a compatibility verdict."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from .. import __version__ as CLI_VERSION
+from .._client import OcmoCtx
+from .._errors import sdk_command
+from .._exit import FAILURE
+from .._output import as_dict
+
+
+@click.command("version")
+@click.option(
+    "--skip-server", is_flag=True, default=False, help="Print CLI and SDK versions only; do not contact the server."
+)
+@click.option("--notice", is_flag=True, default=False, help="Print the bundled product NOTICE text.")
+@click.pass_obj
+@sdk_command
+def version_cmd(ctx: OcmoCtx, skip_server: bool, notice: bool) -> None:
+    """Print CLI, SDK, and server versions with a compatibility verdict."""
+    try:
+        import ocmo as _sdk
+
+        sdk_version = _sdk.__version__
+    except Exception:
+        sdk_version = "unknown"
+
+    if notice:
+        try:
+            from .._notice import load_notice_text
+
+            notice_text = load_notice_text()
+        except Exception as exc:
+            click.echo(f"Failed to load NOTICE: {exc}", err=True)
+            sys.exit(FAILURE)
+        print(notice_text, end="" if notice_text.endswith("\n") else "\n")
+        return
+
+    if skip_server:
+        _print_versions(CLI_VERSION, sdk_version, server_version="(skipped)", verdict="")
+        return
+
+    server_version = "(unavailable)"
+    verdict = ""
+    try:
+        info = ctx.client().version()  # type: ignore[no-untyped-call]
+        data = as_dict(info)
+        server_version = data.get("version", "(unknown)")
+        verdict = _compatibility_verdict(sdk_version, server_version)
+    except SystemExit:
+        raise
+    except Exception as exc:
+        err_str = str(exc)
+        if "OCMO_SERVER" in err_str or "required" in err_str.lower():
+            server_version = "(server not configured)"
+        else:
+            server_version = f"(error: {exc})"
+        verdict = ""
+
+    _print_versions(CLI_VERSION, sdk_version, server_version, verdict)
+
+    if "MAJOR MISMATCH" in verdict:
+        sys.exit(FAILURE)
+
+
+def _print_versions(cli: str, sdk: str, server_version: str, verdict: str) -> None:
+    print(f"ocmo CLI:  {cli}")
+    print(f"ocmo SDK:  {sdk}")
+    print(f"Server:    {server_version}")
+    if verdict:
+        print(f"Compat:    {verdict}")
+
+
+def _compatibility_verdict(sdk_version: str, server_version: str) -> str:
+    sdk_parts = _parse_semver(sdk_version)
+    srv_parts = _parse_semver(server_version)
+    if not sdk_parts or not srv_parts:
+        return "WARNING: could not parse one or both versions"
+    sdk_major, sdk_minor, _ = sdk_parts
+    srv_major, srv_minor, _ = srv_parts
+    if sdk_major != srv_major:
+        return f"MAJOR MISMATCH — SDK major {sdk_major} != server major {srv_major} (not compatible)"
+    diff = abs(sdk_minor - srv_minor)
+    if diff > 2:
+        return (
+            f"WARNING: minor version gap {diff} exceeds the ±2 compatibility window "
+            f"(SDK {sdk_version}, server {server_version})"
+        )
+    return "OK"
+
+
+def _parse_semver(v: str) -> tuple[int, int, int] | None:
+    import re
+
+    m = re.match(r"^(\d+)\.(\d+)\.(\d+)", v)
+    if not m:
+        return None
+    return int(m.group(1)), int(m.group(2)), int(m.group(3))

ocmo_cli/commands/whoami.py

@@ -0,0 +1,12 @@
+"""ocmo whoami — show current identity."""
+
+from __future__ import annotations
+
+from .._client_commands import client_command
+
+whoami_cmd = client_command(
+    "whoami",
+    help="Show the identity of the current authenticated principal.",
+    manifest_key="whoami",
+    method="whoami",
+)