oaken-cli 0.1.0__tar.gz

oaken_cli-0.1.0/.gitignore

@@ -0,0 +1,241 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# --- Oaken Mail: never commit data, mail or secrets ---
+*.db
+*.db-*
+*.sqlite*
+*.eml
+*.mbox
+.env.*
+!.env.example
+token*.json
+credentials*.json
+client_secret*.json
+node_modules/
+site/
+.claude/settings.local.json
+
+# Synthetic test fixtures are committed (no real mail; see docs/architecture/parsing.md).
+!src/oaken/mail/tests/fixtures/**/*.eml
+
+# A real config.toml holds local settings and must never be committed (use config.example.toml).
+config.toml

oaken_cli-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.5
+Name: oaken-cli
+Version: 0.1.0
+Summary: The oaken command line: a thin client of the Oaken Mail core daemon.
+License-Expression: Apache-2.0
+Keywords: ai,cli,email,local-first,mail,mcp,oaken
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: oaken
+Requires-Dist: rich>=13
+Description-Content-Type: text/markdown
+
+# oaken-cli
+
+The `oaken` command: a thin client of the Oaken Mail core daemon. Every command is one operation
+of core's registry, called over the loopback HTTP API. See the CLI reference on the docs site and
+`docs/architecture/daemon.md`.
+
+```text
+uv run oaken --help
+```

oaken_cli-0.1.0/README.md

@@ -0,0 +1,9 @@
+# oaken-cli
+
+The `oaken` command: a thin client of the Oaken Mail core daemon. Every command is one operation
+of core's registry, called over the loopback HTTP API. See the CLI reference on the docs site and
+`docs/architecture/daemon.md`.
+
+```text
+uv run oaken --help
+```

oaken_cli-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "oaken-cli"
+dynamic = ["version"]  # one source of truth: src/oaken/__init__.py (the whole product shares it)
+description = "The oaken command line: a thin client of the Oaken Mail core daemon."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+keywords = ["oaken", "email", "mail", "cli", "mcp", "local-first", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Topic :: Communications :: Email",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "oaken",
+    "rich>=13",
+]
+
+[project.scripts]
+oaken = "oaken_cli:main"
+
+[tool.uv.sources]
+oaken = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# The product releases in lockstep (ADR 0014); every distribution reads its version from the one
+# place oaken declares it, so a single bump moves them all and they can never drift.
+[tool.hatch.version]
+source = "regex"
+path = "../../src/oaken/__init__.py"
+pattern = '__version__ = "(?P<version>[^"]+)"'
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oaken_cli"]
+exclude = ["**/tests/**"]

oaken_cli-0.1.0/src/oaken_cli/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The Oaken command-line client.
+
+The CLI is a *thin* client: it holds no business logic. Every command is a call to a registry
+operation, reached through an :class:`~oaken_cli.client.ApiClient`. In normal use that client
+speaks HTTP to the local core daemon (prompt 16); in tests it wraps the in-process
+``CoreClient`` directly, so the whole CLI is exercised without a socket.
+
+The entry point is :func:`oaken_cli.main.main`, wired as the ``oaken`` console script.
+"""
+
+from oaken_cli.main import main
+
+__all__ = ["main"]

oaken_cli-0.1.0/src/oaken_cli/__main__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Run the CLI as ``python -m oaken_cli``. The console script ``oaken`` is the normal entry point;
+this mirror is handy for ``python -m`` invocation and for measuring startup without the wrapper."""
+
+from __future__ import annotations
+
+from oaken_cli.main import _console_main
+
+if __name__ == "__main__":
+    _console_main()

oaken_cli-0.1.0/src/oaken_cli/client.py

@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The seam between the CLI and core: a small, transport-neutral client.
+
+The CLI never imports core's HTTP wiring or its in-process ``CoreClient`` directly. It programs
+against :class:`ApiClient`, an abstract interface with exactly the operations a thin client needs:
+
+* :meth:`ApiClient.call` — run one registry operation (``POST /v1/ops/{name}`` over HTTP);
+* :meth:`ApiClient.list_ops` — the operation catalogue (``GET /v1/ops``), which drives both the
+  generic ``oaken op NAME`` fallback and ``--help`` text;
+* :meth:`ApiClient.stream_events` — the SSE event stream (``GET /v1/events``), for ``oaken watch``;
+* :meth:`ApiClient.health` — a liveness probe (``GET /v1/health``) used by ``oaken status``.
+
+Two implementations exist (or will):
+
+* :class:`~oaken_cli.inprocess.InProcessApiClient` wraps the in-process ``CoreClient``. It needs no
+  daemon and no socket, so the CLI's whole command surface is testable today (prompt 17).
+* ``HttpApiClient`` speaks to the running daemon. **It is a stub until prompt 16** builds the
+  server; see :mod:`oaken_cli.http`.
+
+The two results a mutation can have — it ran, or it needs confirming first — are modelled by
+:class:`CallResult`, which mirrors core's own ``CallResult`` without importing it, so the HTTP
+decoder and the in-process adapter produce the same shape.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class OpInfo:
+    """One row of the operation catalogue, as a thin client needs it.
+
+    This is the decoded form of a ``/v1/ops`` entry. It is deliberately a plain dataclass, not a
+    pydantic model: the CLI must not import the registry to describe an operation, so that a
+    registry change never forces a CLI release (the generic ``oaken op NAME`` fallback is built
+    from exactly these fields).
+    """
+
+    name: str
+    summary: str
+    permission: str  # "read" | "mutate" | "send"
+    marks_read: bool = False
+    streaming: bool = False
+    input_schema: Mapping[str, Any] = field(default_factory=dict)
+    output_schema: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Proposal:
+    """What a mutation *would* change, returned when it has not been confirmed.
+
+    The CLI shows this to the person and, for an explicit ``--yes`` or an interactive confirm,
+    calls again with ``confirmation_token``. Mirrors core's gate ``Proposal``; ``changes`` may be a
+    prefix of the whole, and ``total_changes`` is always the real count.
+    """
+
+    operation: str
+    summary: str
+    changes: list[dict[str, Any]] = field(default_factory=list)
+    total_changes: int = 0
+    confirmation_token: str = ""
+    expires_at: str = ""
+
+
+@dataclass(frozen=True)
+class CallResult:
+    """The outcome of :meth:`ApiClient.call`: either ``output`` (it ran) or ``proposal`` (confirm
+    first). ``request_id`` ties the call to an audit row and to the daemon's logs."""
+
+    request_id: str
+    output: Any | None = None
+    proposal: Proposal | None = None
+
+    @property
+    def executed(self) -> bool:
+        return self.proposal is None
+
+
+@dataclass(frozen=True)
+class Event:
+    """One line of the SSE stream: a typed event name, its JSON data, and the stream id used to
+    resume with ``Last-Event-ID`` after a reconnect."""
+
+    id: str
+    event: str
+    data: Mapping[str, Any]
+
+
+class ApiClient(ABC):
+    """The thin-client contract. An implementation decides *how* it reaches core (HTTP to the
+    daemon, or the in-process registry); the CLI only ever uses these methods.
+
+    Lifetime: an ``ApiClient`` is an async context manager so an HTTP implementation can hold a
+    connection pool and close it cleanly. The in-process implementation needs no teardown but
+    honours the same protocol.
+    """
+
+    async def __aenter__(self) -> ApiClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:  # noqa: B027 — an optional concrete hook, not abstract
+        """Release any resources (HTTP pool, etc.). The default does nothing."""
+
+    @abstractmethod
+    async def health(self) -> Mapping[str, Any]:
+        """Liveness only. Never requires a working operation; used by ``oaken status`` to tell a
+        running-but-degraded core from one that is down. Raises :class:`CoreUnavailable` when core
+        cannot be reached at all."""
+
+    @abstractmethod
+    async def list_ops(self) -> list[OpInfo]:
+        """The operations this caller may invoke, each with its schemas. Drives the generic
+        ``oaken op NAME`` fallback and the auto-derived ``--help``."""
+
+    @abstractmethod
+    async def call(
+        self,
+        name: str,
+        payload: Mapping[str, Any] | None = None,
+        *,
+        confirm: bool = False,
+        confirmation_token: str | None = None,
+        timeout: float | None = None,  # noqa: ASYNC109
+    ) -> CallResult:
+        """Run one operation. ``timeout`` (seconds) replaces the transport's default wait for the
+        answer, for the few operations that are slow by nature, such as ``ask`` on a local model.
+
+        ``confirm=True`` is the CLI saying *the person at the terminal asked for this exact
+        action*; it is how a human-class caller pre-confirms a mutation. A mutation that is neither
+        confirmed nor accompanied by a ``confirmation_token`` comes back as a :class:`Proposal` and
+        changes nothing.
+        """
+
+    @abstractmethod
+    def stream_events(self, last_event_id: str | None = None) -> AsyncIterator[Event]:
+        """Yield events as they arrive, resuming after ``last_event_id`` when given. Returns an
+        async iterator (not a coroutine) so ``oaken watch`` can ``async for`` over it."""

oaken_cli-0.1.0/src/oaken_cli/commands/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CLI command handlers. Each module holds thin handlers that call registry operations through an
+:class:`~oaken_cli.client.ApiClient`. Imported lazily by :mod:`oaken_cli.main`."""