tangle-cli 0.0.1a1__py3-none-any.whl

tangle_cli/quickstart.py

@@ -0,0 +1,110 @@
+"""Native-free quickstart text for the root ``tangle`` CLI."""
+
+from __future__ import annotations
+
+from textwrap import dedent
+
+from cyclopts import App
+
+
+app = App(name="quickstart", help="Print a concise native-free guide to the Tangle CLI.")
+
+
+QUICKSTART_TEXT = dedent(
+    """
+    Tangle CLI quickstart
+    =====================
+
+    Command families
+    ----------------
+    tangle api ...
+      Pure OpenAPI wrappers around a Tangle API. Commands are generated from
+      the checked-in official schema and can be extended from a live backend
+      schema cache. Use these when you want a direct backend endpoint call.
+
+    tangle sdk ...
+      Hand-written SDK commands for local workflows and compound operations.
+      Some commands are local-only (for example pipeline validation/layout and
+      component generation); others call the API through the generated client
+      while adding domain behavior such as hydration, submit payload shaping,
+      version checks, or config batching.
+
+    Common flags and environment
+    ----------------------------
+    API-backed commands commonly accept:
+      --base-url URL       API base URL (or TANGLE_API_URL)
+      --token TOKEN        bearer token (or TANGLE_API_TOKEN)
+      --auth-header VALUE  full Authorization value, e.g. 'Basic ...' or
+                           'Bearer ...' (or TANGLE_API_AUTH_HEADER /
+                           TANGLE_AUTH_HEADER)
+      -H, --header 'N: V'  extra headers; repeatable (or TANGLE_API_HEADERS)
+      --config PATH        YAML/JSON defaults; CLI values win over config
+      --log-type TYPE      progress logs: console, none, file (SDK commands)
+
+    TANGLE_VERBOSE=1 enables redacted HTTP request/response diagnostics on
+    stderr. It is separate from normal progress logging and should not be
+    required for routine hydration/publish progress.
+
+    Protected API examples
+    ----------------------
+      tangle api refresh --base-url https://api.example \\
+        --auth-header 'Bearer ...' -H 'X-Gateway-Auth: ...'
+
+      tangle api pipeline-runs list --base-url https://api.example \\
+        --auth-header 'Basic ...' -H 'X-Api-Key: ...'
+
+      tangle sdk pipeline-runs submit pipeline.yaml --base-url https://api.example \\
+        --auth-header 'Bearer ...' --log-type console
+
+    Local SDK examples
+    ------------------
+      tangle sdk pipelines validate pipeline.yaml
+      tangle sdk pipelines hydrate pipeline.yaml --output hydrated.yaml
+      tangle sdk components generate from-python component.py --image python:3.12
+      tangle sdk components bump-version component.yaml
+
+    API-backed SDK examples
+    -----------------------
+      tangle sdk published-components search transformer --base-url https://api.example
+      tangle sdk published-components publish component.yaml --dry-run
+      tangle sdk pipeline-runs submit pipeline.yaml --dry-run --log-type none
+      tangle sdk pipeline-runs status RUN_ID --base-url https://api.example
+
+    Generated vs hand-written packages
+    ----------------------------------
+    tangle_cli is the hand-written package: CLI wiring, local SDK workflows,
+    dynamic schema discovery, codegen, logging, hydrator/resolver logic, and
+    extension hooks.
+
+    tangle_api is the generated/native package: checked-in Pydantic models,
+    endpoint operation methods, and the official OpenAPI snapshot. Local-only
+    SDK commands and this quickstart do not need it. Static API-backed commands
+    need tangle-cli[native] or an equivalent local tangle_api.generated package.
+
+    Generated model extensions use private generated bases plus stable public
+    subclasses, e.g. ComponentSpec(ComponentSpecExtensions,
+    _ComponentSpecGenerated). Extension bases are left of the generated base in
+    the MRO, and downstream --model-extension-module values can add/override
+    behavior while preserving generated fields and stable names.
+
+    Discover more
+    -------------
+      tangle --help
+      tangle api --help
+      tangle api refresh --help
+      tangle sdk --help
+      tangle sdk pipelines --help
+      tangle sdk pipeline-runs submit --help
+
+    See README.md for codegen/autogen instructions and extension surfaces:
+    hydrator resolvers, PipelineRunHooks, ComponentPublishHook, and shared CLI
+    options/logging helpers.
+    """
+).strip()
+
+
+@app.default
+def quickstart() -> None:
+    """Print a concise native-free guide to the Tangle CLI."""
+
+    print(QUICKSTART_TEXT)

tangle_cli/secrets.py

@@ -0,0 +1,156 @@
+"""Read/write helpers for Tangle secret metadata and values.
+
+Secret values are accepted only for explicit create/update operations and are
+never included in returned metadata dictionaries.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Protocol
+
+from .handler import TangleCliHandler
+
+
+class SecretClient(Protocol):
+    """Subset of the generated static client used by secret commands."""
+
+    def secrets_list(self) -> Any: ...
+
+    def secrets_create(
+        self,
+        secret_name: str,
+        secret_value: str,
+        description: str | None = None,
+        expires_at: str | None = None,
+    ) -> Any: ...
+
+    def secrets_update(
+        self,
+        secret_name: str,
+        secret_value: str,
+        description: str | None = None,
+        expires_at: str | None = None,
+    ) -> Any: ...
+
+    def secrets_delete(self, secret_name: str) -> Any: ...
+
+
+class SecretValueError(ValueError):
+    """Raised when secret value CLI/config inputs are invalid."""
+
+
+class SecretsManager(TangleCliHandler):
+    """Secret resource manager with injectable client construction.
+
+    Downstream packages can inject an authenticated client directly or provide a
+    lazy ``client_factory``. Returned dictionaries intentionally omit secret
+    values and only include metadata.
+    """
+
+    def __init__(
+        self,
+        client: SecretClient | None = None,
+        *,
+        client_factory: Any | None = None,
+        logger: Any | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(client=client, client_factory=client_factory, logger=logger, **kwargs)
+
+    @staticmethod
+    def resolve_secret_value(value: str | None, from_env: str | None) -> str:
+        """Resolve the secret value from either ``--value`` or ``--from-env``.
+
+        Error messages intentionally mention only the option/env-var name and
+        never include the secret value.
+        """
+
+        if value is not None and from_env is not None:
+            raise SecretValueError("specify either --value or --from-env, not both")
+        if from_env is not None:
+            resolved = os.environ.get(from_env)
+            if resolved is None:
+                raise SecretValueError(f"environment variable '{from_env}' is not set")
+            return resolved
+        if value is not None:
+            return value
+        raise SecretValueError("either --value or --from-env is required")
+
+    @staticmethod
+    def secret_metadata(secret: Any) -> dict[str, Any]:
+        """Return JSON-safe secret metadata, excluding any secret value fields."""
+
+        entry: dict[str, Any] = {}
+        for field in ("secret_name", "created_at", "updated_at", "expires_at", "description"):
+            value = _value_from_mapping_or_object(secret, field)
+            if value is not None:
+                entry[field] = str(value)
+        return entry
+
+    def list(self) -> dict[str, Any]:
+        """List secret metadata without exposing secret values."""
+
+        response = self._require_client().secrets_list()
+        raw_secrets = _value_from_mapping_or_object(response, "secrets", []) or []
+        secrets = [self.secret_metadata(secret) for secret in raw_secrets]
+        return {"status": "success", "count": len(secrets), "secrets": secrets}
+
+    def create(
+        self,
+        secret_name: str,
+        *,
+        value: str | None = None,
+        from_env: str | None = None,
+        description: str | None = None,
+        expires_at: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a secret using generated static API operations."""
+
+        secret_value = self.resolve_secret_value(value, from_env)
+        secret = self._require_client().secrets_create(
+            secret_name,
+            secret_value,
+            description=description,
+            expires_at=expires_at,
+        )
+        return {"status": "success", "action": "created", "secret": self.secret_metadata(secret)}
+
+    def update(
+        self,
+        secret_name: str,
+        *,
+        value: str | None = None,
+        from_env: str | None = None,
+        description: str | None = None,
+        expires_at: str | None = None,
+    ) -> dict[str, Any]:
+        """Update a secret using generated static API operations."""
+
+        secret_value = self.resolve_secret_value(value, from_env)
+        secret = self._require_client().secrets_update(
+            secret_name,
+            secret_value,
+            description=description,
+            expires_at=expires_at,
+        )
+        return {"status": "success", "action": "updated", "secret": self.secret_metadata(secret)}
+
+    def delete(self, secret_name: str) -> dict[str, Any]:
+        """Delete a secret using generated static API operations."""
+
+        self._require_client().secrets_delete(secret_name)
+        return {"status": "success", "action": "deleted", "secret_name": secret_name}
+
+
+def _value_from_mapping_or_object(value: Any, key: str, default: Any = None) -> Any:
+    if isinstance(value, dict):
+        return value.get(key, default)
+    return getattr(value, key, default)
+
+
+__all__ = [
+    "SecretClient",
+    "SecretValueError",
+    "SecretsManager",
+]

tangle_cli/secrets_cli.py

@@ -0,0 +1,269 @@
+"""`tangle sdk secrets` command implementation."""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated, Any, Callable
+
+from cyclopts import App, Parameter
+
+from .args_container import ArgsContainer
+from .cli_helpers import (
+    LazyTangleApiClient,
+    api_arg_specs,
+    include_env_credentials_for_args,
+    load_args_or_exit,
+    print_json,
+)
+from .cli_options import (
+    AuthHeaderOption,
+    BaseUrlOption,
+    ConfigOption,
+    HeaderOption,
+    LogTypeOption,
+    TokenOption,
+)
+from .logger import Logger, logger_for_log_type
+from .secrets import SecretsManager, SecretValueError
+
+ValueOption = Annotated[
+    str | None,
+    Parameter(
+        name="--value",
+        alias="-v",
+        help="Secret value. Prefer --from-env to avoid shell history exposure.",
+    ),
+]
+FromEnvOption = Annotated[
+    str | None,
+    Parameter(
+        name="--from-env",
+        alias="-e",
+        help="Read secret value from this environment variable.",
+    ),
+]
+DescriptionOption = Annotated[
+    str | None,
+    Parameter(name="--description", alias="-d", help="Secret description."),
+]
+ExpiresAtOption = Annotated[
+    str | None,
+    Parameter(help="Expiration datetime (ISO 8601)."),
+]
+ForceOption = Annotated[
+    bool,
+    Parameter(help="Skip confirmation prompt."),
+]
+
+app = App(name="secrets", help="Manage Tangle secrets.")
+
+
+def _client(args: ArgsContainer, *, cli_base_url: str | None, command_name: str) -> LazyTangleApiClient:
+    return LazyTangleApiClient(
+        base_url=args.base_url,
+        token=args.token,
+        auth_header=args.auth_header,
+        header=args.header,
+        include_env_credentials=include_env_credentials_for_args(args, cli_base_url),
+        command_name=command_name,
+    )
+
+
+def _run_secret_action(
+    config: str | None,
+    cli_base_url: str | None,
+    specs: dict[str, tuple[Any, ...]],
+    fn: Callable[[Any, ArgsContainer, Logger], dict[str, Any]],
+) -> None:
+    results: list[dict[str, Any]] = []
+    for args in load_args_or_exit(config, **specs):
+        logger, finalize_logs = logger_for_log_type(getattr(args, "log_type", "console"))
+        try:
+            client = _client(args, cli_base_url=cli_base_url, command_name="secret commands")
+            try:
+                results.append(fn(client, args, logger))
+            except SecretValueError as exc:
+                raise SystemExit(str(exc)) from exc
+        finally:
+            finalize_logs()
+
+    print_json(results[0] if len(results) == 1 else {"status": "success", "results": results})
+
+
+def _secret_mutation_specs(
+    *,
+    secret_name: str | None,
+    value: str | None,
+    from_env: str | None,
+    description: str | None,
+    expires_at: str | None,
+    base_url: str | None,
+    token: str | None,
+    auth_header: str | None,
+    header: list[str] | None,
+    log_type: str,
+) -> dict[str, tuple[Any, ...]]:
+    return {
+        "secret_name": ("secret_name", secret_name, None, False, True),
+        "value": (value, None),
+        "from_env": (from_env, None),
+        "description": (description, None),
+        "expires_at": (expires_at, None),
+        "log_type": (log_type, "console"),
+        **api_arg_specs(base_url=base_url, token=token, auth_header=auth_header, header=header),
+    }
+
+
+def _confirm_delete(secret_name: str) -> None:
+    prompt = f"Are you sure you want to delete secret '{secret_name}'? [y/N]: "
+    print(prompt, end="", file=sys.stderr, flush=True)
+    try:
+        response = input()
+    except EOFError as exc:  # pragma: no cover - defensive for non-interactive shells
+        raise SystemExit("Delete cancelled") from exc
+    if response.strip().lower() not in {"y", "yes"}:
+        raise SystemExit("Delete cancelled")
+
+
+@app.command(name="list")
+def secrets_list(
+    *,
+    base_url: BaseUrlOption = None,
+    token: TokenOption = None,
+    auth_header: AuthHeaderOption = None,
+    header: HeaderOption = None,
+    config: ConfigOption = None,
+    log_type: LogTypeOption = "console",
+) -> None:
+    """List secret metadata. Secret values are never returned."""
+
+    specs = {
+        "log_type": (log_type, "console"),
+        **api_arg_specs(base_url=base_url, token=token, auth_header=auth_header, header=header),
+    }
+
+    def action(client: Any, args: ArgsContainer, logger: Logger) -> dict[str, Any]:
+        result = SecretsManager(client=client).list()
+        logger.info(f"Listed {result['count']} secret(s).")
+        return result
+
+    _run_secret_action(config, base_url, specs, action)
+
+
+@app.command(name="create")
+def secrets_create(
+    secret_name: str | None = None,
+    *,
+    value: ValueOption = None,
+    from_env: FromEnvOption = None,
+    description: DescriptionOption = None,
+    expires_at: ExpiresAtOption = None,
+    base_url: BaseUrlOption = None,
+    token: TokenOption = None,
+    auth_header: AuthHeaderOption = None,
+    header: HeaderOption = None,
+    config: ConfigOption = None,
+    log_type: LogTypeOption = "console",
+) -> None:
+    """Create a new secret."""
+
+    specs = _secret_mutation_specs(
+        secret_name=secret_name,
+        value=value,
+        from_env=from_env,
+        description=description,
+        expires_at=expires_at,
+        base_url=base_url,
+        token=token,
+        auth_header=auth_header,
+        header=header,
+        log_type=log_type,
+    )
+
+    def action(client: Any, args: ArgsContainer, logger: Logger) -> dict[str, Any]:
+        result = SecretsManager(client=client).create(
+            args.secret_name,
+            value=args.value,
+            from_env=args.from_env,
+            description=args.description,
+            expires_at=args.expires_at,
+        )
+        logger.info(f"Created secret: {args.secret_name}")
+        return result
+
+    _run_secret_action(config, base_url, specs, action)
+
+
+@app.command(name="update")
+def secrets_update(
+    secret_name: str | None = None,
+    *,
+    value: ValueOption = None,
+    from_env: FromEnvOption = None,
+    description: DescriptionOption = None,
+    expires_at: ExpiresAtOption = None,
+    base_url: BaseUrlOption = None,
+    token: TokenOption = None,
+    auth_header: AuthHeaderOption = None,
+    header: HeaderOption = None,
+    config: ConfigOption = None,
+    log_type: LogTypeOption = "console",
+) -> None:
+    """Update an existing secret."""
+
+    specs = _secret_mutation_specs(
+        secret_name=secret_name,
+        value=value,
+        from_env=from_env,
+        description=description,
+        expires_at=expires_at,
+        base_url=base_url,
+        token=token,
+        auth_header=auth_header,
+        header=header,
+        log_type=log_type,
+    )
+
+    def action(client: Any, args: ArgsContainer, logger: Logger) -> dict[str, Any]:
+        result = SecretsManager(client=client).update(
+            args.secret_name,
+            value=args.value,
+            from_env=args.from_env,
+            description=args.description,
+            expires_at=args.expires_at,
+        )
+        logger.info(f"Updated secret: {args.secret_name}")
+        return result
+
+    _run_secret_action(config, base_url, specs, action)
+
+
+@app.command(name="delete")
+def secrets_delete(
+    secret_name: str | None = None,
+    *,
+    force: ForceOption = False,
+    base_url: BaseUrlOption = None,
+    token: TokenOption = None,
+    auth_header: AuthHeaderOption = None,
+    header: HeaderOption = None,
+    config: ConfigOption = None,
+    log_type: LogTypeOption = "console",
+) -> None:
+    """Delete a secret. Prompts for confirmation unless ``--force`` is used."""
+
+    specs = {
+        "secret_name": ("secret_name", secret_name, None, False, True),
+        "force": (force, False),
+        "log_type": (log_type, "console"),
+        **api_arg_specs(base_url=base_url, token=token, auth_header=auth_header, header=header),
+    }
+
+    def action(client: Any, args: ArgsContainer, logger: Logger) -> dict[str, Any]:
+        if not args.force:
+            _confirm_delete(args.secret_name)
+        result = SecretsManager(client=client).delete(args.secret_name)
+        logger.info(f"Deleted secret: {args.secret_name}")
+        return result
+
+    _run_secret_action(config, base_url, specs, action)