ream-artifacts 0.1.0__tar.gz

ream_artifacts-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.3
+Name: ream-artifacts
+Version: 0.1.0
+Summary: A self-hosted artifacts publisher: agents publish HTML pages over a keyed API; Jeremy views them in an Authelia-gated gallery.
+Author: Jeremy Brown
+Author-email: Jeremy Brown <jeremy@tenfourty.com>
+Requires-Dist: cryptography>=46 ; extra == 'server'
+Requires-Dist: fastapi>=0.141.1 ; extra == 'server'
+Requires-Dist: html5lib>=1.1 ; extra == 'server'
+Requires-Dist: markdown-it-py>=4 ; extra == 'server'
+Requires-Dist: markupsafe>=3.0.3 ; extra == 'server'
+Requires-Dist: mdit-py-plugins>=0.5 ; extra == 'server'
+Requires-Dist: psycopg[binary]>=3.3.6 ; extra == 'server'
+Requires-Dist: python-multipart>=0.0.32 ; extra == 'server'
+Requires-Dist: uvicorn>=0.53.0 ; extra == 'server'
+Requires-Dist: zstandard>=0.25 ; extra == 'server'
+Requires-Python: >=3.12
+Provides-Extra: server
+Description-Content-Type: text/markdown
+
+# Ream (formerly artifacts)
+
+A self-hosted page publisher: agents publish an HTML
+page over a keyed API and get back a stable URL. A person views published pages
+in a gallery behind a sign-in; each page is served from its own
+`<id>.<content domain>` hostname behind a capability token in the URL.
+
+## Development
+
+```bash
+uv run pytest        # run tests
+uv run ruff check src tests   # lint
+```
+
+Requires Python 3.12 exactly (pinned in `.python-version`) — a later task's
+test dependency (`pgserver`) has no wheels for 3.13+.
+
+## Run locally
+
+```bash
+export DATABASE_URL=postgresql://...   # a real Postgres; migrate() runs on startup
+uv run uvicorn ream.serve:app_from_env --factory --reload
+```
+
+The router is fail-closed: `/healthz` only answers 200 with the gallery's own
+`Host` (the host of `REAM_GALLERY_ORIGIN`; `localhost:8000` on a fresh install)
+and 404 on anything else, so curl it with that Host header, not the
+bare address.
+
+## Mint a key for an agent
+
+A token is generated where it will be used and never crosses a terminal, a
+transcript, or a network hop — only its SHA-256 is ever registered:
+
+```bash
+# On the machine (or pod) that will hold the key:
+artifacts-admin new-key --agent my-agent --out <your key file>
+
+# Then, with the sha256 that command just printed, on the running pod:
+kubectl -n artifacts exec deploy/artifacts -- artifacts-admin register-key \
+  --agent my-agent --sha256 <the printed sha256>
+```
+
+`artifacts-admin revoke-key <key_id>` and `artifacts-admin list-keys` manage
+keys from there; neither ever prints a token.
+
+## The skill
+
+One skill, `GET /api/v1/skill.md` (open, no key), in the open SKILL.md format: save it wherever
+your agent keeps skills. It is named `ream` and fires whenever the agent shows or shares something
+beyond a short chat answer (a report, a plan, a chart, a diagram, a comparison), not only on the
+words "page" or "publish". With a key set up it publishes to Ream instead of a host's built-in
+artifacts or canvas panel; with none it falls back to that panel and says why. A page carries a
+question only when the agent is blocked on the person or needs their choice. It names no house, so
+it works for any agent on any host; a deployment's own skill adds only its look and keys.
+
+## Publish a page
+
+The command is `ream`, with a verb for each job (`ream publish`, `ream ask`,
+`ream wait`; `ream --help` lists them). The older `artifacts-publish`,
+`artifacts-decide` and the other `artifacts-*` commands keep working for good,
+as do the `ARTIFACTS_*` settings, and `/api/v1/artifacts` answers exactly as
+`/api/v1/pages` does (the same handlers, so a POST to either works).
+
+```bash
+ream publish page.html --title "My page"
+ream publish page.html --update <id>   # after editing page.html
+ream publish --list
+```
+
+Where the key comes from, in the order to prefer:
+
+```bash
+# A vault hands it over on a descriptor; no cleartext copy exists. Where keys are
+# vaulted, a wrapper does it (here `artifacts-key`, with your seat's name):
+ARTIFACTS_SEAT=<seat> artifacts-key -- ream publish page.html --title "My page"
+
+# Or any store of your own that can open one:
+ream publish --key-fd 3 page.html --title "My page" 3< <(pass show artifacts/key)
+
+# Or a file, mode 600 -- it refuses anything looser:
+REAM_KEY_FILE=~/.config/artifacts/key ream publish --list
+```
+
+## Tidy one up
+
+Everything Jeremy can do to a page in the gallery, an agent can do to its own
+pages — his rule, 20 Sep 2026: *"ideally agents can take all the same actions a
+human can."* None of these send the body, so none of them needs the file:
+
+```bash
+ream publish --rename <id> --title "Its real name"
+ream publish --archive <id>     # off the wall; nothing is deleted
+ream publish --unarchive <id>
+ream publish --pin <id>         # leads the gallery
+ream publish --unpin <id>
+ream publish --duplicate <id>   # a copy at a new address
+```
+
+Over HTTP these are `POST /api/v1/pages/{id}/{archive,rename,pin}`, each
+scoped to the calling key's own agent: another seat's page answers 404, and so
+does a page that does not exist — the same 404, so a key cannot be used to
+learn which ids are real.
+
+`$REAM_API` (default `https://artifacts.tenfourty.site/api/v1`) and
+`$REAM_KEY_FILE` (default `~/.config/artifacts/key`) point it elsewhere;
+`--key-file` overrides both for one call.
+
+## How deploys happen
+
+Every push to `main` runs `.forgejo/workflows/ci.yml`: tests, then an image
+build pushed to the forge's registry as `<repo>:<sha12>`, then a pull request on
+the deployment's own repo that moves its `core.lock` to that image
+(`.forgejo/scripts/core-lock-pr.sh`). That repo builds the deployed image and opens
+the pin PR; production moves when that PR is merged. The runbook is
+`docs/agent/runbooks/image-from-ream-homelab.md`. This repo keeps no deployment
+values: they are in the deployment's own repo.

ream_artifacts-0.1.0/README.md

@@ -0,0 +1,117 @@
+# Ream (formerly artifacts)
+
+A self-hosted page publisher: agents publish an HTML
+page over a keyed API and get back a stable URL. A person views published pages
+in a gallery behind a sign-in; each page is served from its own
+`<id>.<content domain>` hostname behind a capability token in the URL.
+
+## Development
+
+```bash
+uv run pytest        # run tests
+uv run ruff check src tests   # lint
+```
+
+Requires Python 3.12 exactly (pinned in `.python-version`) — a later task's
+test dependency (`pgserver`) has no wheels for 3.13+.
+
+## Run locally
+
+```bash
+export DATABASE_URL=postgresql://...   # a real Postgres; migrate() runs on startup
+uv run uvicorn ream.serve:app_from_env --factory --reload
+```
+
+The router is fail-closed: `/healthz` only answers 200 with the gallery's own
+`Host` (the host of `REAM_GALLERY_ORIGIN`; `localhost:8000` on a fresh install)
+and 404 on anything else, so curl it with that Host header, not the
+bare address.
+
+## Mint a key for an agent
+
+A token is generated where it will be used and never crosses a terminal, a
+transcript, or a network hop — only its SHA-256 is ever registered:
+
+```bash
+# On the machine (or pod) that will hold the key:
+artifacts-admin new-key --agent my-agent --out <your key file>
+
+# Then, with the sha256 that command just printed, on the running pod:
+kubectl -n artifacts exec deploy/artifacts -- artifacts-admin register-key \
+  --agent my-agent --sha256 <the printed sha256>
+```
+
+`artifacts-admin revoke-key <key_id>` and `artifacts-admin list-keys` manage
+keys from there; neither ever prints a token.
+
+## The skill
+
+One skill, `GET /api/v1/skill.md` (open, no key), in the open SKILL.md format: save it wherever
+your agent keeps skills. It is named `ream` and fires whenever the agent shows or shares something
+beyond a short chat answer (a report, a plan, a chart, a diagram, a comparison), not only on the
+words "page" or "publish". With a key set up it publishes to Ream instead of a host's built-in
+artifacts or canvas panel; with none it falls back to that panel and says why. A page carries a
+question only when the agent is blocked on the person or needs their choice. It names no house, so
+it works for any agent on any host; a deployment's own skill adds only its look and keys.
+
+## Publish a page
+
+The command is `ream`, with a verb for each job (`ream publish`, `ream ask`,
+`ream wait`; `ream --help` lists them). The older `artifacts-publish`,
+`artifacts-decide` and the other `artifacts-*` commands keep working for good,
+as do the `ARTIFACTS_*` settings, and `/api/v1/artifacts` answers exactly as
+`/api/v1/pages` does (the same handlers, so a POST to either works).
+
+```bash
+ream publish page.html --title "My page"
+ream publish page.html --update <id>   # after editing page.html
+ream publish --list
+```
+
+Where the key comes from, in the order to prefer:
+
+```bash
+# A vault hands it over on a descriptor; no cleartext copy exists. Where keys are
+# vaulted, a wrapper does it (here `artifacts-key`, with your seat's name):
+ARTIFACTS_SEAT=<seat> artifacts-key -- ream publish page.html --title "My page"
+
+# Or any store of your own that can open one:
+ream publish --key-fd 3 page.html --title "My page" 3< <(pass show artifacts/key)
+
+# Or a file, mode 600 -- it refuses anything looser:
+REAM_KEY_FILE=~/.config/artifacts/key ream publish --list
+```
+
+## Tidy one up
+
+Everything Jeremy can do to a page in the gallery, an agent can do to its own
+pages — his rule, 20 Sep 2026: *"ideally agents can take all the same actions a
+human can."* None of these send the body, so none of them needs the file:
+
+```bash
+ream publish --rename <id> --title "Its real name"
+ream publish --archive <id>     # off the wall; nothing is deleted
+ream publish --unarchive <id>
+ream publish --pin <id>         # leads the gallery
+ream publish --unpin <id>
+ream publish --duplicate <id>   # a copy at a new address
+```
+
+Over HTTP these are `POST /api/v1/pages/{id}/{archive,rename,pin}`, each
+scoped to the calling key's own agent: another seat's page answers 404, and so
+does a page that does not exist — the same 404, so a key cannot be used to
+learn which ids are real.
+
+`$REAM_API` (default `https://artifacts.tenfourty.site/api/v1`) and
+`$REAM_KEY_FILE` (default `~/.config/artifacts/key`) point it elsewhere;
+`--key-file` overrides both for one call.
+
+## How deploys happen
+
+Every push to `main` runs `.forgejo/workflows/ci.yml`: tests, then an image
+build pushed to the forge's registry as `<repo>:<sha12>`, then a pull request on
+the deployment's own repo that moves its `core.lock` to that image
+(`.forgejo/scripts/core-lock-pr.sh`). That repo builds the deployed image and opens
+the pin PR; production moves when that PR is merged. The runbook is
+`docs/agent/runbooks/image-from-ream-homelab.md`. This repo keeps no deployment
+values: they are in the deployment's own repo.

ream_artifacts-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "ream-artifacts"
+version = "0.1.0"
+description = "A self-hosted artifacts publisher: agents publish HTML pages over a keyed API; Jeremy views them in an Authelia-gated gallery."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+
+[[project.authors]]
+name = "Jeremy Brown"
+email = "jeremy@tenfourty.com"
+
+[project.optional-dependencies]
+server = [
+    "cryptography>=46",
+    "fastapi>=0.141.1",
+    "html5lib>=1.1",
+    "markdown-it-py>=4",
+    "markupsafe>=3.0.3",
+    "mdit-py-plugins>=0.5",
+    "psycopg[binary]>=3.3.6",
+    "python-multipart>=0.0.32",
+    "uvicorn>=0.53.0",
+    "zstandard>=0.25",
+]
+
+[project.scripts]
+ream = "ream.cli:main"
+artifacts-admin = "ream.admin:main"
+artifacts-publish = "ream.client:run"
+artifacts-decide = "ream.decide:run"
+artifacts-republish = "ream.republish:run"
+artifacts-connect = "ream.connect_cli:run"
+
+[tool.uv.build-backend]
+module-name = [
+    "ream",
+    "artifacts",
+]
+
+[tool.pytest.ini_options]
+addopts = "--dist=worksteal -rs"
+timeout = 300
+timeout_method = "signal"
+markers = [
+    "slow(reason): genuinely needs more than a second; says why",
+    "postgres_only: reads Postgres's catalogue or runs Postgres's own SQL; skipped when REAM_TEST_DB=sqlite",
+    "plugin_loader: drives the plug-in loader with entry points it fakes; REAM_PLUGINS is unset for it (the core-bare CI job sets it to none for everything else)",
+    "no_default_comments: leave a publish exactly as the test sends it (the suite otherwise adds comments on to a new page's publish, which the service now requires)",
+    "background_thumbnails: publishes in this test start the real background thumbnail render (off by default in tests; see tests/conftest.py)",
+]
+
+[tool.ruff.lint]
+extend-select = [
+    "S",
+    "B",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "S311",
+    "F811",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "pgserver>=0.1.4",
+    "playwright>=1.63.0",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.16.8",
+]

ream_artifacts-0.1.0/pyproject.toml.orig

@@ -0,0 +1,109 @@
+[project]
+# The install name, which `uv tool install` takes, is `ream-artifacts` (docs/decisions.md, 10 Nov
+# 2026): `ream` on public PyPI is somebody else's package. Nothing else is renamed: the `ream`
+# command, the `artifacts-*` commands, the import packages `ream` and `artifacts`.
+name = "ream-artifacts"
+version = "0.1.0"
+description = "A self-hosted artifacts publisher: agents publish HTML pages over a keyed API; Jeremy views them in an Authelia-gated gallery."
+readme = "README.md"
+authors = [
+    { name = "Jeremy Brown", email = "jeremy@tenfourty.com" }
+]
+requires-python = ">=3.12"
+# NOTHING by default, on purpose (homelab-ij8.68, 23 Sep 2026). The agent tools
+# -- artifacts-publish, -decide, -republish -- use only the standard library, and
+# the service hands this package to agents on other machines from an open
+# address. An agent that wants to publish a page must not have to install a web
+# framework and a database driver to do it. The service itself installs the
+# `server` extra (Dockerfile, CI); for local work: `uv sync --all-extras`.
+dependencies = []
+
+[project.optional-dependencies]
+server = [
+    "cryptography>=46",
+    "fastapi>=0.141.1",
+    "html5lib>=1.1",
+    "markdown-it-py>=4",
+    "markupsafe>=3.0.3",
+    "mdit-py-plugins>=0.5",
+    "psycopg[binary]>=3.3.6",
+    "python-multipart>=0.0.32",
+    "uvicorn>=0.53.0",
+    "zstandard>=0.25",
+]
+
+[project.scripts]
+ream = "ream.cli:main"
+# The old command names work for good, beside the verbs of `ream`.
+artifacts-admin = "ream.admin:main"
+artifacts-publish = "ream.client:run"
+artifacts-decide = "ream.decide:run"
+artifacts-republish = "ream.republish:run"
+artifacts-connect = "ream.connect_cli:run"
+
+# Two top-level packages ship in the one wheel: `ream`, and `artifacts`, the old import
+# name kept for good (a shim whose modules ARE the ream modules).
+[tool.uv.build-backend]
+module-name = ["ream", "artifacts"]
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "pgserver>=0.1.4",
+    "playwright>=1.63.0",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.16.8",
+]
+
+[tool.pytest.ini_options]
+# worksteal, not xdist's default `load`: idle workers take tests from the
+# busiest one's tail, so the run ends when the work does, not when the unluckiest
+# worker's last chunk does. Inert without -n. See pytest_collection_modifyitems
+# in tests/conftest.py for where the slow tests go.
+# -rs: the summary names every skipped test and why. Browser tests skip where
+# there is no headless browser (a laptop without one; CI installs chromium and sets
+# REAM_REQUIRE_BROWSER=1, so there a missing browser fails), and a bare "13 skipped"
+# hid that for weeks (runcove-5t3oj.77).
+addopts = "--dist=worksteal -rs"
+# A test that hangs fails after 5 minutes with every thread's stack printed,
+# naming itself, instead of holding a CI builder until the job's own limit
+# (6 Oct 2026: a test job sat idle for 35 minutes and left no clue). The
+# slowest test takes about 9 s; this only ever catches a hang.
+timeout = 300
+# "signal", not "thread": the thread method dumps stacks and kills the worker,
+# and xdist drops a dead worker's stderr -- on 7 Oct 2026 a CI hang left only
+# "node down: Not properly terminated". The signal method fails the hung test
+# in place with its traceback, and the worker carries on.
+timeout_method = "signal"
+# `slow`: a test that genuinely needs more than a second, each with a one-line
+# reason at the mark. At most ten may carry it; everything else stays under 1 s.
+markers = [
+    "slow(reason): genuinely needs more than a second; says why",
+    "postgres_only: reads Postgres's catalogue or runs Postgres's own SQL; skipped when REAM_TEST_DB=sqlite",
+    "plugin_loader: drives the plug-in loader with entry points it fakes; REAM_PLUGINS is unset for it (the core-bare CI job sets it to none for everything else)",
+    "no_default_comments: leave a publish exactly as the test sends it (the suite otherwise adds comments on to a new page's publish, which the service now requires)",
+    "background_thumbnails: publishes in this test start the real background thumbnail render (off by default in tests; see tests/conftest.py)",
+]
+
+[tool.ruff.lint]
+# S (bandit) and B (bugbear) are worth enabling deliberately on a service whose
+# whole job is handling credentials and publishing agent-authored HTML -- on
+# top of ruff's E4/E7/E9/F + isort defaults, not replacing them.
+extend-select = ["S", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+# S101 flags `assert` -- pytest's idiom for every assertion, not a risk here.
+# S311 flags `random.Random` as unfit for cryptographic use -- true, and
+# irrelevant to a seeded fuzz corpus for a property test, which wants
+# reproducible pseudo-randomness, never secrecy.
+# F811 flags a pytest fixture imported from test_client and then taken as a
+# parameter -- how pytest works, not a mistake. Per-line noqa stopped covering
+# it once the formatter wrapped long signatures (homelab-ij8.25).
+"tests/**" = ["S101", "S311", "F811"]

ream_artifacts-0.1.0/src/artifacts/__init__.py

@@ -0,0 +1,91 @@
+"""The old import name, kept for good: `import artifacts` is `import ream`.
+
+The package was renamed to `ream` (docs/decisions.md, "Ream inside the code too"). Callers
+outside this repository still write `import artifacts`, `from artifacts.settings import ...`,
+`artifacts.plugin_api`, or name `artifacts.client:run` as an entry point, and all of it keeps
+working. Nothing here is a copy:
+
+* `artifacts` itself becomes the `ream` module object (so `resources.files("artifacts")` finds
+  the schema and the templates in `ream`);
+* `artifacts.X` is the SAME module object as `ream.X`, found by the finder below, so
+  `settings.override(...)` or a monkeypatch through either name acts on one module, never on
+  two copies that each hold their own state.
+
+This file reads no environment and holds no logic of the service.
+"""
+
+import importlib
+import importlib.abc
+import importlib.util
+import sys
+from importlib.machinery import ModuleSpec
+
+import ream
+
+_OLD = "artifacts"
+_NEW = "ream"
+
+
+class _AliasFinder(importlib.abc.MetaPathFinder, importlib.abc.Loader):
+    """Answers `artifacts.<x>` with the already-imported `ream.<x>`."""
+
+    def __init__(self) -> None:
+        self._real_specs: dict[str, ModuleSpec] = {}
+
+    def find_spec(self, fullname, path=None, target=None) -> ModuleSpec | None:
+        if not fullname.startswith(_OLD + "."):
+            return None
+        real = _NEW + fullname[len(_OLD) :]
+        try:
+            found = importlib.util.find_spec(real)
+        except ModuleNotFoundError:
+            return None
+        if found is None:
+            return None
+        self._real_spec(fullname)
+        return importlib.util.spec_from_loader(fullname, self)
+
+    def create_module(self, spec: ModuleSpec):
+        return importlib.import_module(_NEW + spec.name[len(_OLD) :])
+
+    def _real_spec(self, fullname: str) -> ModuleSpec | None:
+        """The spec `ream.<x>` was really imported with. Once `artifacts.<x>` has been
+        imported the import system overwrites `module.__spec__` with the alias spec, so
+        the first real one seen is kept."""
+        real = _NEW + fullname[len(_OLD) :]
+        if real not in self._real_specs:
+            found = importlib.util.find_spec(real)
+            if found is None or found.name != real:
+                return found
+            self._real_specs[real] = found
+        return self._real_specs[real]
+
+    def exec_module(self, module) -> None:
+        """Nothing to run: the module was executed under its real name. The import
+        system has just set `module.__spec__` to the alias spec; put the real one back."""
+        real = self._real_spec(_OLD + module.__name__[len(_NEW) :])
+        if real is not None:
+            module.__spec__ = real
+
+    def _real_loader(self, fullname: str):
+        real = self._real_spec(fullname)
+        if real is None or real.loader is None:
+            raise ImportError(f"no loader for {fullname}", name=fullname)
+        return real.loader
+
+    # `python -m artifacts.<x>` (runpy) asks the alias spec's loader for the code.
+    def get_code(self, fullname: str):
+        return self._real_loader(fullname).get_code(_NEW + fullname[len(_OLD) :])
+
+    def get_source(self, fullname: str):
+        return self._real_loader(fullname).get_source(_NEW + fullname[len(_OLD) :])
+
+    def is_package(self, fullname: str) -> bool:
+        return self._real_loader(fullname).is_package(_NEW + fullname[len(_OLD) :])
+
+
+if not any(isinstance(f, _AliasFinder) for f in sys.meta_path):
+    sys.meta_path.insert(0, _AliasFinder())
+
+# `import artifacts` hands back the ream package itself.
+sys.modules[__name__] = ream