untaped 2.4.4__tar.gz

untaped-2.4.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Alexis Beaulieu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

untaped-2.4.4/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: untaped
+Version: 2.4.4
+Summary: A batteries-included CLI framework for building standalone DevOps tools.
+Author: Alexis Beaulieu
+Author-email: Alexis Beaulieu <alexisbeaulieu97@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: cyclopts>=4.16.0,<5
+Requires-Dist: filelock>=3.29.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: prompt-toolkit>=3.0.52
+Requires-Dist: pydantic>=2.13.3
+Requires-Dist: pydantic-settings>=2.14.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: truststore>=0.10.4
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# untaped
+
+**untaped** is a batteries-included CLI framework for building standalone
+DevOps tools on [cyclopts](https://cyclopts.readthedocs.io/). It is an SDK, not
+an app: there is no central `untaped` command. You build a tool, depend on the
+SDK, and ship an independent CLI.
+
+The SDK gives every tool, for free:
+
+- **Config** — a shared `~/.untaped/config.yml` with top-level `active:` /
+  `profiles:`, per-profile SDK `http` / `ui` settings, and each tool's own
+  profile settings plus tool-managed top-level state.
+- **Profiles** — named overlays (`dev`, `prod`, `homelab`) and a `--profile`
+  root option, built in.
+- **Themes** — built-in theme presets for consistent terminal styling.
+- **Output** — consistent `--format json|yaml|table|raw|pipe` and `--columns`,
+  so commands compose. `pipe` is a self-describing NDJSON record stream another
+  untaped tool can read back. `emit(...)` renders a single entity as a vertical
+  detail view or a sequence as a collection, dispatching by shape.
+- **HTTP / UI helpers** — an `HttpClient` with profile-aware TLS, automatic
+  retries for transient failures (`RetryPolicy`), and pagination helpers, plus a
+  `UiContext` for messages, prompts, and progress.
+- **Config tooling** — `<tool> config doctor` diagnoses the shared file and
+  `<tool> config edit` opens it in `$VISUAL`/`$EDITOR`; a `--quiet` root option
+  mutes progress and `success`/`info` chatter.
+
+You import the surface from `untaped.api` (re-exported from the `untaped`
+package root), declare a `ToolSpec`, and call `run_tool(app, spec)` from your
+tool's `main()`. The contract surface is the `__all__` list in
+[`src/untaped/api.py`](./src/untaped/api.py).
+
+```python
+# my_tool/__main__.py
+from untaped.api import create_app, run_tool, ToolSpec
+from my_tool.settings import MyProfile
+
+app = create_app(...)
+
+def main() -> None:
+    run_tool(app, ToolSpec(
+        command="untaped-mytool",
+        section="mytool",
+        profile_model=MyProfile,
+    ))
+```
+
+```toml
+# pyproject.toml
+[project]
+dependencies = [
+    "untaped>=2.4.4,<3",
+]
+
+[project.scripts]
+untaped-mytool = "my_tool.__main__:main"
+```
+
+Suite repos may keep a `[tool.uv.sources]` git tag while developing against an
+exact SDK release. Published wheels are built with `uv build --no-sources`, so
+package metadata resolves from the declared PyPI range.
+
+## Requirements
+
+Python 3.14 and [uv](https://docs.astral.sh/uv/).
+
+## The suite
+
+Seven tools are built on the SDK. Each is an independent CLI installed into its
+own `uv tool` environment. As each PyPI-backed tool completes its first package
+release, install it by package name:
+
+```bash
+uv tool install untaped-github
+uv tool install untaped-jira
+uv tool install untaped-awx
+uv tool install untaped-ansible
+uv tool install untaped-workspace
+uv tool install untaped-recipe
+uv tool install git+https://github.com/alexisbeaulieu97/untaped-apple-health.git
+```
+
+`untaped-apple-health` is outside the current PyPI release wave; install it from
+git until that repo owns a package release workflow.
+
+Because every tool reads the same `~/.untaped/config.yml` and shares the same
+`--format pipe` envelope, independently installed tools interoperate and
+compose:
+
+```bash
+untaped-awx job-templates list --format raw --columns name \
+  | fzf \
+  | untaped-awx job-templates get --stdin --format json
+```
+
+## Documentation
+
+User-facing docs live in [`docs/`](./docs/README.md):
+
+- [Building a tool with the untaped SDK](./docs/plugins.md) — the guide to
+  declaring a `ToolSpec`, wiring `run_tool`, and packaging an independent CLI.
+- [Configuration](./docs/configuration.md) — the `~/.untaped/config.yml`
+  format, profiles, secrets, and TLS.
+- [Agent Skills](./docs/skills.md) — how each tool ships and installs
+  Codex/Claude agent skills.
+- [Releasing](./docs/release.md) — PyPI/TestPyPI workflow, Trusted Publisher
+  setup, and recovery rules.
+- [Architecture decisions](./docs/decisions.md) — the settled ADRs behind the
+  SDK-only direction.
+
+Per-tool command references live in each tool's own repo:
+
+- [GitHub](https://github.com/alexisbeaulieu97/untaped-github)
+- [Jira](https://github.com/alexisbeaulieu97/untaped-jira)
+- [AWX / AAP](https://github.com/alexisbeaulieu97/untaped-awx)
+- [Ansible](https://github.com/alexisbeaulieu97/untaped-ansible)
+- [Workspaces](https://github.com/alexisbeaulieu97/untaped-workspace)
+- [Recipe](https://github.com/alexisbeaulieu97/untaped-recipe)
+- [Apple Health](https://github.com/alexisbeaulieu97/untaped-apple-health)
+
+## Security
+
+Please report suspected vulnerabilities privately. See
+[SECURITY.md](./SECURITY.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [AGENTS.md](./AGENTS.md) for the
+local workflow, architecture rules, and recipes for extending the SDK and its
+tools.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

untaped-2.4.4/README.md

@@ -0,0 +1,133 @@
+# untaped
+
+**untaped** is a batteries-included CLI framework for building standalone
+DevOps tools on [cyclopts](https://cyclopts.readthedocs.io/). It is an SDK, not
+an app: there is no central `untaped` command. You build a tool, depend on the
+SDK, and ship an independent CLI.
+
+The SDK gives every tool, for free:
+
+- **Config** — a shared `~/.untaped/config.yml` with top-level `active:` /
+  `profiles:`, per-profile SDK `http` / `ui` settings, and each tool's own
+  profile settings plus tool-managed top-level state.
+- **Profiles** — named overlays (`dev`, `prod`, `homelab`) and a `--profile`
+  root option, built in.
+- **Themes** — built-in theme presets for consistent terminal styling.
+- **Output** — consistent `--format json|yaml|table|raw|pipe` and `--columns`,
+  so commands compose. `pipe` is a self-describing NDJSON record stream another
+  untaped tool can read back. `emit(...)` renders a single entity as a vertical
+  detail view or a sequence as a collection, dispatching by shape.
+- **HTTP / UI helpers** — an `HttpClient` with profile-aware TLS, automatic
+  retries for transient failures (`RetryPolicy`), and pagination helpers, plus a
+  `UiContext` for messages, prompts, and progress.
+- **Config tooling** — `<tool> config doctor` diagnoses the shared file and
+  `<tool> config edit` opens it in `$VISUAL`/`$EDITOR`; a `--quiet` root option
+  mutes progress and `success`/`info` chatter.
+
+You import the surface from `untaped.api` (re-exported from the `untaped`
+package root), declare a `ToolSpec`, and call `run_tool(app, spec)` from your
+tool's `main()`. The contract surface is the `__all__` list in
+[`src/untaped/api.py`](./src/untaped/api.py).
+
+```python
+# my_tool/__main__.py
+from untaped.api import create_app, run_tool, ToolSpec
+from my_tool.settings import MyProfile
+
+app = create_app(...)
+
+def main() -> None:
+    run_tool(app, ToolSpec(
+        command="untaped-mytool",
+        section="mytool",
+        profile_model=MyProfile,
+    ))
+```
+
+```toml
+# pyproject.toml
+[project]
+dependencies = [
+    "untaped>=2.4.4,<3",
+]
+
+[project.scripts]
+untaped-mytool = "my_tool.__main__:main"
+```
+
+Suite repos may keep a `[tool.uv.sources]` git tag while developing against an
+exact SDK release. Published wheels are built with `uv build --no-sources`, so
+package metadata resolves from the declared PyPI range.
+
+## Requirements
+
+Python 3.14 and [uv](https://docs.astral.sh/uv/).
+
+## The suite
+
+Seven tools are built on the SDK. Each is an independent CLI installed into its
+own `uv tool` environment. As each PyPI-backed tool completes its first package
+release, install it by package name:
+
+```bash
+uv tool install untaped-github
+uv tool install untaped-jira
+uv tool install untaped-awx
+uv tool install untaped-ansible
+uv tool install untaped-workspace
+uv tool install untaped-recipe
+uv tool install git+https://github.com/alexisbeaulieu97/untaped-apple-health.git
+```
+
+`untaped-apple-health` is outside the current PyPI release wave; install it from
+git until that repo owns a package release workflow.
+
+Because every tool reads the same `~/.untaped/config.yml` and shares the same
+`--format pipe` envelope, independently installed tools interoperate and
+compose:
+
+```bash
+untaped-awx job-templates list --format raw --columns name \
+  | fzf \
+  | untaped-awx job-templates get --stdin --format json
+```
+
+## Documentation
+
+User-facing docs live in [`docs/`](./docs/README.md):
+
+- [Building a tool with the untaped SDK](./docs/plugins.md) — the guide to
+  declaring a `ToolSpec`, wiring `run_tool`, and packaging an independent CLI.
+- [Configuration](./docs/configuration.md) — the `~/.untaped/config.yml`
+  format, profiles, secrets, and TLS.
+- [Agent Skills](./docs/skills.md) — how each tool ships and installs
+  Codex/Claude agent skills.
+- [Releasing](./docs/release.md) — PyPI/TestPyPI workflow, Trusted Publisher
+  setup, and recovery rules.
+- [Architecture decisions](./docs/decisions.md) — the settled ADRs behind the
+  SDK-only direction.
+
+Per-tool command references live in each tool's own repo:
+
+- [GitHub](https://github.com/alexisbeaulieu97/untaped-github)
+- [Jira](https://github.com/alexisbeaulieu97/untaped-jira)
+- [AWX / AAP](https://github.com/alexisbeaulieu97/untaped-awx)
+- [Ansible](https://github.com/alexisbeaulieu97/untaped-ansible)
+- [Workspaces](https://github.com/alexisbeaulieu97/untaped-workspace)
+- [Recipe](https://github.com/alexisbeaulieu97/untaped-recipe)
+- [Apple Health](https://github.com/alexisbeaulieu97/untaped-apple-health)
+
+## Security
+
+Please report suspected vulnerabilities privately. See
+[SECURITY.md](./SECURITY.md).
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [AGENTS.md](./AGENTS.md) for the
+local workflow, architecture rules, and recipes for extending the SDK and its
+tools.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

untaped-2.4.4/pyproject.toml

@@ -0,0 +1,117 @@
+[project]
+name = "untaped"
+version = "2.4.4"
+description = "A batteries-included CLI framework for building standalone DevOps tools."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Alexis Beaulieu", email = "alexisbeaulieu97@gmail.com" },
+]
+requires-python = ">=3.14"
+dependencies = [
+    "cyclopts>=4.16.0,<5",
+    "filelock>=3.29.0",
+    "httpx>=0.28.1",
+    "prompt-toolkit>=3.0.52",
+    "pydantic>=2.13.3",
+    "pydantic-settings>=2.14.0",
+    "pyyaml>=6.0.3",
+    "rich>=15.0.0",
+    "truststore>=0.10.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.20.2",
+    "pre-commit>=4.6.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "respx>=0.23.1",
+    "ruff>=0.15.12",
+    "types-pyyaml>=6.0.12.20260408",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+    "TID",  # flake8-tidy-imports
+    "C90",  # mccabe complexity (gate set in [tool.ruff.lint.mccabe])
+    "RUF",  # ruff-specific
+]
+extend-select = ["PLC0415"]
+ignore = []
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 12
+
+[tool.ruff.lint.per-file-ignores]
+# Tests can use assert statements; in-function imports are routine and
+# idiomatic in tests (no startup-latency cost).
+"**/tests/**" = ["S101", "PLC0415"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+warn_unused_configs = true
+warn_unreachable = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+disallow_any_generics = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+plugins = ["pydantic.mypy"]
+# Type-check src/ only; tests are validated by running them.
+packages = [
+    "untaped",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--cov",
+    "--cov-report=term-missing",
+    "--import-mode=importlib",
+]
+markers = [
+    "integration: cross-package or external-service tests",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["src"]
+omit = ["**/tests/**", "**/__main__.py"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+skip_covered = false
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "@(abc\\.)?abstractmethod",
+]

untaped-2.4.4/src/untaped/__init__.py

@@ -0,0 +1,10 @@
+"""The untaped SDK — a batteries-included CLI framework built on cyclopts.
+
+This package root re-exports the public surface defined in :mod:`untaped.api`,
+so ``from untaped import X`` and ``from untaped.api import X`` are equivalent.
+"""
+
+from untaped import api as _api
+from untaped.api import *  # noqa: F403
+
+__all__ = list(_api.__all__)

untaped-2.4.4/src/untaped/api.py

@@ -0,0 +1,130 @@
+"""The untaped SDK surface.
+
+Tools import from this module (``from untaped.api import ...``) instead of
+reaching into SDK internals. Names listed in ``__all__`` are the SDK contract:
+additions are backwards-compatible; removing a name or changing its behaviour
+is a major SDK version event. Internal modules stay free to reorganize as long
+as this surface keeps resolving. ``untaped`` (the package root) re-exports this
+exact surface, so ``from untaped import X`` and ``from untaped.api import X``
+are equivalent.
+"""
+
+from __future__ import annotations
+
+from untaped.app_context import AppContext, app_context
+from untaped.batch import BatchOutcome, batch_apply
+from untaped.cli import (
+    ColumnsOption,
+    FormatOption,
+    clamp_parallel,
+    create_app,
+    echo,
+    emit,
+    existing_directory,
+    existing_file,
+    parse_kv_pairs,
+    raise_usage,
+    render_rows,
+    report_errors,
+    resolve_each,
+)
+from untaped.config_file import ensure_config, mutate_tool_state, read_tool_state
+from untaped.errors import (
+    ConfigError,
+    HttpError,
+    HttpStatusError,
+    HttpTransportError,
+    UntapedError,
+    first_validation_error,
+)
+from untaped.http import (
+    HttpClient,
+    RetryPolicy,
+    connected_client,
+    paginate_offset,
+    paginate_pages,
+    resolve_verify,
+)
+from untaped.output import OutputFormat
+from untaped.pipe import PipeEnvelope, common_kind, is_envelope_line, parse_envelope_line
+from untaped.progress import ProgressHandle
+from untaped.prompts import PromptChoice
+from untaped.run import build_tool_app, run_tool
+from untaped.settings import (
+    HttpSettings,
+    get_config_section,
+    get_core_settings,
+    get_settings,
+)
+from untaped.stdin import read_identifiers, read_records, read_stdin
+from untaped.theme import ThemeSpec
+from untaped.tool import SkillAsset, ToolSpec, register_tool
+from untaped.ui import UiContext, ui_context
+
+
+def invalidate_settings_cache() -> None:
+    """Drop the cached settings instance so the next read re-resolves.
+
+    Root-option handlers (e.g. the built-in ``--profile``) call this after
+    changing process state that feeds settings resolution.
+    """
+    get_settings.cache_clear()
+
+
+__all__ = [
+    "AppContext",
+    "BatchOutcome",
+    "ColumnsOption",
+    "ConfigError",
+    "FormatOption",
+    "HttpClient",
+    "HttpError",
+    "HttpSettings",
+    "HttpStatusError",
+    "HttpTransportError",
+    "OutputFormat",
+    "PipeEnvelope",
+    "ProgressHandle",
+    "PromptChoice",
+    "RetryPolicy",
+    "SkillAsset",
+    "ThemeSpec",
+    "ToolSpec",
+    "UiContext",
+    "UntapedError",
+    "app_context",
+    "batch_apply",
+    "build_tool_app",
+    "clamp_parallel",
+    "common_kind",
+    "connected_client",
+    "create_app",
+    "echo",
+    "emit",
+    "ensure_config",
+    "existing_directory",
+    "existing_file",
+    "first_validation_error",
+    "get_config_section",
+    "get_core_settings",
+    "get_settings",
+    "invalidate_settings_cache",
+    "is_envelope_line",
+    "mutate_tool_state",
+    "paginate_offset",
+    "paginate_pages",
+    "parse_envelope_line",
+    "parse_kv_pairs",
+    "raise_usage",
+    "read_identifiers",
+    "read_records",
+    "read_stdin",
+    "read_tool_state",
+    "register_tool",
+    "render_rows",
+    "report_errors",
+    "resolve_each",
+    "resolve_verify",
+    "run_tool",
+    "ui_context",
+]

untaped-2.4.4/src/untaped/app_context.py

@@ -0,0 +1,70 @@
+"""Per-invocation tool execution context.
+
+``app_context()`` resolves settings exactly once and hands a tool a frozen
+value object. Profile (or any other scope) selection happens before command
+dispatch via the root ``--profile`` option, so nothing about the resolution
+leaks into ambient process state from here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+from untaped.errors import ConfigError
+from untaped.settings import HttpSettings, Settings, get_settings
+from untaped.theme import UiSettings, resolve_theme_or_default
+from untaped.ui import UiContext, ui_context
+
+
+@dataclass(frozen=True)
+class AppContext:
+    """Resolved settings plus typed accessors handed to a tool command."""
+
+    settings: Settings
+
+    def section[T: BaseModel](self, name: str, model_cls: type[T]) -> T:
+        """Return one typed, registered settings section.
+
+        Unlike :func:`untaped.settings.get_config_section`, this never builds
+        a one-off model for unregistered sections — the context is a frozen
+        snapshot, so it can only serve sections that were registered (via
+        :func:`untaped.tool.register_tool`) before it was created.
+        """
+        value = getattr(self.settings, name, None)
+        if value is None:
+            raise ConfigError(
+                f"config section {name!r} is not registered; register the tool's "
+                f"section with untaped.tool.register_tool before resolving a context"
+            )
+        if isinstance(value, model_cls):
+            return value
+        if isinstance(value, BaseModel):
+            return model_cls.model_validate(value.model_dump())
+        return model_cls.model_validate(value)
+
+    @property
+    def http(self) -> HttpSettings:
+        """Cross-cutting HTTP settings for building clients."""
+        return self.settings.http
+
+    def ui(self, *, strict: bool = True) -> UiContext:
+        """The themed UI context for messages and prompts.
+
+        Built from this context's frozen settings snapshot, so the theme is
+        stable for the life of the context even if the settings cache is later
+        invalidated. ``strict=False`` degrades a theme-resolution
+        :class:`ConfigError` (e.g. an unknown theme name) to the default theme.
+        """
+        theme = resolve_theme_or_default(lambda: self.section("ui", UiSettings), strict=strict)
+        return ui_context(theme=theme)
+
+
+def app_context() -> AppContext:
+    """Resolve effective settings once and return a frozen :class:`AppContext`.
+
+    Profile selection happens before dispatch via the root ``--profile`` option,
+    so no parameters are needed here.
+    """
+    return AppContext(settings=get_settings())