mantos 0.1.0__tar.gz

mantos-0.1.0/.gitignore

@@ -0,0 +1 @@
+dist/

mantos-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: mantos
+Version: 0.1.0
+Summary: The Mantos CLI — reach your Mantos tenant's API from a terminal
+Project-URL: Homepage, https://mantos.cloud
+Author: Systematic Labs LLC
+License-Expression: LicenseRef-Proprietary
+Keywords: agents,api,cli,mantos
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary 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 :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: click>=8.2
+Requires-Dist: httpx>=0.25
+Description-Content-Type: text/markdown
+
+# mantos
+
+The command-line client for [Mantos](https://mantos.cloud) — reach your tenant's
+API from a terminal, a CI job, a container, or an agent session.
+
+```bash
+pipx install mantos     # or: pip install mantos
+```
+
+## One environment variable
+
+A Mantos API key carries its own tenant slug, so the key is the whole
+configuration:
+
+```bash
+export MANTOS_API_KEY=mtk_<tenant>_<keyid>_<secret>
+
+mantos api GET api/tenant/v1/envs/dev/agents
+```
+
+There is nothing else to set — no host, no tenant, no profile. Mint a key in
+the Mantos console (**Settings → API keys**); the secret is shown once, at mint,
+and is not recoverable afterwards.
+
+## Commands
+
+```
+mantos api METHOD PATH [--field K=V] [--raw-field K=V] [--json] [--timeout S]
+mantos config set-host HOST
+mantos config show
+```
+
+`mantos api` reaches any tenant API path directly. `PATH` includes any query
+string, and a leading slash is optional — on Git Bash, omitting it avoids the
+shell rewriting the argument into a Windows filesystem path before the CLI sees
+it.
+
+`--field K=V` builds a JSON body, parsing `V` as JSON when it parses and sending
+it as a string when it does not; `--raw-field` always sends a string. Neither is
+accepted on `GET` or `HEAD`, where the API takes no body — silently dropping a
+field would let you believe a filter was applied that never was.
+
+## Output, so a parser and a person can both read it
+
+The response body is the only thing written to **stdout**. The status line for
+a failure goes to **stderr**. Pipe stdout straight into `jq` without stripping
+anything, and still see why a call went red.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | The request succeeded (2xx). |
+| `1` | The request was made and did not succeed — any non-2xx other than 401, plus a transport failure. |
+| `2` | The invocation was wrong, or `MANTOS_API_KEY` is not set. Nothing was sent. |
+| `3` | The credential was not accepted (401). |
+
+A **403 is `1`, not `3`**. Authenticated-but-refused is a different fact from
+credential-rejected: a key whose grants are narrower than its owner's authority
+is *supposed* to be refused inside a scope it only partly holds, and that is the
+authorization gate working rather than a broken key.
+
+## Host resolution
+
+`MANTOS_HOST` › the tenant named by the key › a host stored with
+`mantos config set-host`.
+
+The environment variable wins so a support session, a smoke test, or a
+one-off against another deployment needs no stored state and leaves none behind.
+A stored host is the last resort precisely because it is invisible: a pin left
+behind by an earlier session must not silently outrank the credential in front
+of it.
+
+---
+
+Mantos is a product of Systematic Labs LLC. This client talks to a deployed
+Mantos tenant over HTTPS and contains no server code.

mantos-0.1.0/README.md

@@ -0,0 +1,77 @@
+# mantos
+
+The command-line client for [Mantos](https://mantos.cloud) — reach your tenant's
+API from a terminal, a CI job, a container, or an agent session.
+
+```bash
+pipx install mantos     # or: pip install mantos
+```
+
+## One environment variable
+
+A Mantos API key carries its own tenant slug, so the key is the whole
+configuration:
+
+```bash
+export MANTOS_API_KEY=mtk_<tenant>_<keyid>_<secret>
+
+mantos api GET api/tenant/v1/envs/dev/agents
+```
+
+There is nothing else to set — no host, no tenant, no profile. Mint a key in
+the Mantos console (**Settings → API keys**); the secret is shown once, at mint,
+and is not recoverable afterwards.
+
+## Commands
+
+```
+mantos api METHOD PATH [--field K=V] [--raw-field K=V] [--json] [--timeout S]
+mantos config set-host HOST
+mantos config show
+```
+
+`mantos api` reaches any tenant API path directly. `PATH` includes any query
+string, and a leading slash is optional — on Git Bash, omitting it avoids the
+shell rewriting the argument into a Windows filesystem path before the CLI sees
+it.
+
+`--field K=V` builds a JSON body, parsing `V` as JSON when it parses and sending
+it as a string when it does not; `--raw-field` always sends a string. Neither is
+accepted on `GET` or `HEAD`, where the API takes no body — silently dropping a
+field would let you believe a filter was applied that never was.
+
+## Output, so a parser and a person can both read it
+
+The response body is the only thing written to **stdout**. The status line for
+a failure goes to **stderr**. Pipe stdout straight into `jq` without stripping
+anything, and still see why a call went red.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | The request succeeded (2xx). |
+| `1` | The request was made and did not succeed — any non-2xx other than 401, plus a transport failure. |
+| `2` | The invocation was wrong, or `MANTOS_API_KEY` is not set. Nothing was sent. |
+| `3` | The credential was not accepted (401). |
+
+A **403 is `1`, not `3`**. Authenticated-but-refused is a different fact from
+credential-rejected: a key whose grants are narrower than its owner's authority
+is *supposed* to be refused inside a scope it only partly holds, and that is the
+authorization gate working rather than a broken key.
+
+## Host resolution
+
+`MANTOS_HOST` › the tenant named by the key › a host stored with
+`mantos config set-host`.
+
+The environment variable wins so a support session, a smoke test, or a
+one-off against another deployment needs no stored state and leaves none behind.
+A stored host is the last resort precisely because it is invisible: a pin left
+behind by an earlier session must not silently outrank the credential in front
+of it.
+
+---
+
+Mantos is a product of Systematic Labs LLC. This client talks to a deployed
+Mantos tenant over HTTPS and contains no server code.

mantos-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+# The `mantos` CLI — its own distribution, and the reason this directory exists.
+#
+# 🔴 **Why the source MOVED rather than getting a pyproject alongside it.**
+# Hatchling refuses any package path outside the project root. Measured, not
+# assumed: `packages = ["../src/mantos_cli"]` fails the build with
+# `Path #1 in field 'tool.hatch.build.only-include' must be relative`. A second
+# distribution therefore needs a second project root with its sources *under*
+# it, which is why `src/mantos_cli/` became `cli/src/mantos_cli/`. No build
+# backend we would want takes the parent-relative shortcut — setuptools tolerates
+# it for a wheel and then breaks sdists and editable installs, which is a worse
+# place to discover the same limit.
+#
+# 🔴 **The distribution name `mantos` is the CLIENT** — the thing a tenant
+# installs gets the guessable name. The server distribution is `mantos-server`
+# (repo root), and it was renamed *for this*: two distributions sharing a name
+# means `pip install -e ./cli` in a venv holding the editable server install
+# silently uninstalls the server, leaving `import mantos` resolving to nothing
+# while every CLI command still works. The root pyproject carries the detail.
+#
+# The PACKAGE names never collided and still do not: `mantos` (server) and
+# `mantos_cli` (this). Only the distribution names did.
+[project]
+name = "mantos"
+dynamic = ["version"]
+description = "The Mantos CLI — reach your Mantos tenant's API from a terminal"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "Systematic Labs LLC" }]
+keywords = ["mantos", "cli", "agents", "api"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+]
+
+# The CLI's whole runtime dependency set, and it is meant to stay this short —
+# a client a tenant installs onto a laptop, a CI runner or an agent session
+# should not drag a stack behind it.
+#
+# 🔴 The click floor is >=8.2 for a behavioural reason, not a feature one:
+# `tests/cli` asserts the response body lands on stdout and the failure line on
+# stderr, which is what lets an agent pipe stdout straight into a parser.
+# Click 8.1's `CliRunner` merges the two and `result.stderr` raises, so a
+# resolver that picked 8.1 would fail those tests in a way that reads like a CLI
+# defect rather than a pin.
+#
+# `tests/cli/test_packaging.py` asserts this list actually covers every
+# third-party module `mantos_cli` imports — declaring one and importing two is
+# invisible in a dev venv, where the server distribution has already installed
+# everything.
+dependencies = [
+    "click>=8.2",
+    "httpx>=0.25",
+]
+
+[project.urls]
+Homepage = "https://mantos.cloud"
+
+# The command name is `mantos` and it is independent of the distribution name —
+# `httpie` installs `http`. Both happen to coincide here; the settled decision
+# is the *command*, recorded in specifications/handoff-programmatic-access.md.
+#
+# This is also the line that could not exist in the root pyproject: a console
+# script in the SERVER wheel pointing at `mantos_cli` would install a command
+# that only fails when someone runs it, on a deployed image, during an incident.
+# `tests/cli/test_packaging.py` still asserts the root declares no such script.
+[project.scripts]
+mantos = "mantos_cli.cli:main"
+
+[build-system]
+# >=1.27 for PEP 639 license expressions (`license = "LicenseRef-…"`). The root
+# distribution's floor is >=1.21 and does not need raising for that.
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+# One source of truth for the version: the literal in the package. The CLI
+# deliberately does NOT read `mantos.__version__` — that import would cross the
+# very boundary that makes this distribution separable (`.importlinter` contract
+# `cli-independent-of-server`), so the two version literals are independent by
+# design and are allowed to diverge.
+[tool.hatch.version]
+path = "src/mantos_cli/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mantos_cli"]
+
+[tool.hatch.build.targets.sdist]
+# An explicit list rather than hatchling's default sweep of the project root:
+# the default would ship whatever else ends up in this directory (a `dist/`, a
+# stray venv) into the artifact that gets uploaded to PyPI.
+include = ["src/mantos_cli", "README.md"]
+# ⚠️ `include` does NOT bound the sdist on its own. Hatchling force-includes the
+# `.gitignore` it used for exclusions, and with none in this directory it walked
+# up and shipped the REPO ROOT's — publishing our internal path layout inside a
+# public artifact. `exclude = [".gitignore"]` does not stop it (measured). The
+# fix is the local `cli/.gitignore`, which is why that two-line file exists and
+# must not be deleted as redundant with the root one.
+#
+# Read the built tarball rather than trusting this block —
+# `tests/cli/test_packaging.py` does exactly that.

mantos-0.1.0/src/mantos_cli/__init__.py

@@ -0,0 +1,26 @@
+"""The ``mantos`` CLI — a client for the Mantos tenant REST API.
+
+🔴 **This package is its own distribution, not part of the server wheel.** Same
+precedent, and the same reason, as ``sandbox_runner`` and ``egress_authz``: a
+tenant should not install the control plane to get a client. Since P4d that is
+structural rather than an exclusion — the package lives under ``cli/``, which
+has its own ``pyproject.toml`` (published as ``mantos``, against the server's
+``mantos-server``). ``tests/cli/test_packaging.py`` asserts it against both
+built artifacts rather than trusting this comment.
+
+The corollary is the import boundary: **``mantos_cli`` must never import
+``mantos``.** It talks to the deployed control plane over HTTP and knows
+nothing of its internals — that is what makes it separable at all. The
+``.importlinter`` contract ``cli-independent-of-server`` enforces it, because
+one ``from mantos.control...`` import would undo the separation silently and
+still pass every test.
+
+Version is a standalone literal for the same reason: reading
+``mantos.__version__`` would be an import across that boundary.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

mantos-0.1.0/src/mantos_cli/__main__.py

@@ -0,0 +1,20 @@
+"""``python -m mantos_cli`` entry point.
+
+⚠️ **This module holds nothing but the call.** ``python -m pkg`` imports the
+module a *second* time under the name ``__main__``, so anything defined here —
+a class, an exception, a sentinel — exists twice under two identities, and
+``except`` clauses silently stop matching (memory
+``reference_dash_m_double_import``; #2380). Keeping the file to one import and
+one call makes that unrepresentable.
+
+A tenant runs ``mantos``, not this: the console script ships with the CLI's own
+distribution (``cli/pyproject.toml``, P4d). This module stays because
+``python -m mantos_cli`` is what works from a source checkout, before anything
+is installed.
+"""
+
+from __future__ import annotations
+
+from mantos_cli.cli import main
+
+raise SystemExit(main())