staryard 0.1.0__tar.gz

staryard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Bobowski
+
+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.

staryard-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: staryard
+Version: 0.1.0
+Summary: Command line for a Yard host.
+Keywords: yard,cli,containers,deploy
+Author: Adam Bobowski
+Author-email: Adam Bobowski <adam.bobowski@wratilabs.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Systems Administration
+Requires-Dist: stario>=4,<5 ; extra == 'server'
+Requires-Dist: uvloop>=0.21.0 ; extra == 'server'
+Requires-Python: >=3.14
+Project-URL: Changelog, https://github.com/Bobowski/yard/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/Bobowski/yard
+Project-URL: Issues, https://github.com/Bobowski/yard/issues
+Project-URL: Repository, https://github.com/Bobowski/yard
+Provides-Extra: server
+Description-Content-Type: text/markdown
+
+# Yard
+
+Yard runs each app in its own container. You push a repo. Yard builds the Containerfile and starts the container. Caddy sends public traffic to that container.
+
+## Slot
+
+A slot is one app. The container name is the slot name.
+
+A slot points at one repo and one branch. The repo must already contain one of these files:
+
+- `Containerfile`
+- `Dockerfile`
+- `ops/Containerfile`
+- `ops/Dockerfile`
+
+A push to that branch builds the image and starts the container. Yard removes the slot when that branch is merged or deleted.
+
+`--every 5m` makes a job. Yard keeps one run at a time. The next run uses the same container name.
+
+## Host
+
+Yard keeps its files under `/srv/yard`. Each slot keeps its files under `/srv/yard/data/<name>`.
+
+Caddy listens on port 8443. The host forwards port 443 to that port. Yard posts the Caddy config to a Unix socket.
+
+## CLI
+
+The command is `yard`. The package name is `staryard`. PyPI already has a package named `yard`.
+
+```sh
+uv tool install staryard
+yard --version
+```
+
+Python 3.14 is required. `yard login` stores the host and the token on this computer.
+
+`staryard[server]` installs the server libraries. The host still runs the container image.
+
+## Install
+
+Run the script on the VM as root. A second run repairs a partial install. A healthy Yard container stays in place.
+
+```sh
+./install.sh --domain yard.example.com
+```
+
+The script installs `ghcr.io/bobowski/yard:latest`. A finished run has checked the health page, the container route, and the path to Let's Encrypt. With `--domain` it also checks the certificate and `https://<domain>/health`.
+
+The script prints an admin token. Log in from your computer:
+
+```sh
+yard login --url https://yard.example.com --token <token>
+```
+
+The package must be public. A private package needs `podman login ghcr.io` on the VM before the script.
+
+GitHub Actions builds the image when this directory is the root of the repo. The workflow publishes `ghcr.io/bobowski/yard:latest` for `linux/amd64`.
+
+## Update Yard
+
+`yard update` pulls `ghcr.io/bobowski/yard:latest` and swaps the Yard container. `yard rollback` starts the previous image.
+
+A repo on this host replaces that image:
+
+```sh
+yard settings --self-repo yard
+yard update
+```
+
+Clear the repo to return to the image:
+
+```sh
+yard settings --self-image
+yard update
+```
+
+## Add an app
+
+Run this in the app directory. The directory name is the repo name and the slot name.
+
+```sh
+yard init --domain heldso.example.com
+git push -u yard main
+```
+
+`yard init` makes a git repo when the directory has none. It makes the Yard repo and the slot. It adds a git remote named `yard`. It does not push.
+
+Pass `--domain` for a public host. Pass `--every 5m` for a job. One of them is required. `--name` sets the repo name and the slot name. `--repo` and `--slot` set one each.
+
+`yard repo new`, `yard repo link`, and `yard slot new` do those steps one at a time.
+
+## Commands
+
+Run `yard` to see every command. These are the common ones:
+
+- `yard slot list` shows each slot, its data size, and how long the last build took. The last row is the host total.
+- `yard slot edit <name>` changes the slot file.
+- `yard slot logs <name>` reads the container log.
+- `yard settings` sets the public host, the Caddy email, and the Yard image.
+
+A terminal prints text. Any other stdout prints JSON.
+
+## Develop
+
+The server command is `python -m app.main`.
+
+```sh
+uv run pytest
+STARIO_LOOP=uvloop uv run python -m app.main
+```

staryard-0.1.0/README.md

@@ -0,0 +1,110 @@
+# Yard
+
+Yard runs each app in its own container. You push a repo. Yard builds the Containerfile and starts the container. Caddy sends public traffic to that container.
+
+## Slot
+
+A slot is one app. The container name is the slot name.
+
+A slot points at one repo and one branch. The repo must already contain one of these files:
+
+- `Containerfile`
+- `Dockerfile`
+- `ops/Containerfile`
+- `ops/Dockerfile`
+
+A push to that branch builds the image and starts the container. Yard removes the slot when that branch is merged or deleted.
+
+`--every 5m` makes a job. Yard keeps one run at a time. The next run uses the same container name.
+
+## Host
+
+Yard keeps its files under `/srv/yard`. Each slot keeps its files under `/srv/yard/data/<name>`.
+
+Caddy listens on port 8443. The host forwards port 443 to that port. Yard posts the Caddy config to a Unix socket.
+
+## CLI
+
+The command is `yard`. The package name is `staryard`. PyPI already has a package named `yard`.
+
+```sh
+uv tool install staryard
+yard --version
+```
+
+Python 3.14 is required. `yard login` stores the host and the token on this computer.
+
+`staryard[server]` installs the server libraries. The host still runs the container image.
+
+## Install
+
+Run the script on the VM as root. A second run repairs a partial install. A healthy Yard container stays in place.
+
+```sh
+./install.sh --domain yard.example.com
+```
+
+The script installs `ghcr.io/bobowski/yard:latest`. A finished run has checked the health page, the container route, and the path to Let's Encrypt. With `--domain` it also checks the certificate and `https://<domain>/health`.
+
+The script prints an admin token. Log in from your computer:
+
+```sh
+yard login --url https://yard.example.com --token <token>
+```
+
+The package must be public. A private package needs `podman login ghcr.io` on the VM before the script.
+
+GitHub Actions builds the image when this directory is the root of the repo. The workflow publishes `ghcr.io/bobowski/yard:latest` for `linux/amd64`.
+
+## Update Yard
+
+`yard update` pulls `ghcr.io/bobowski/yard:latest` and swaps the Yard container. `yard rollback` starts the previous image.
+
+A repo on this host replaces that image:
+
+```sh
+yard settings --self-repo yard
+yard update
+```
+
+Clear the repo to return to the image:
+
+```sh
+yard settings --self-image
+yard update
+```
+
+## Add an app
+
+Run this in the app directory. The directory name is the repo name and the slot name.
+
+```sh
+yard init --domain heldso.example.com
+git push -u yard main
+```
+
+`yard init` makes a git repo when the directory has none. It makes the Yard repo and the slot. It adds a git remote named `yard`. It does not push.
+
+Pass `--domain` for a public host. Pass `--every 5m` for a job. One of them is required. `--name` sets the repo name and the slot name. `--repo` and `--slot` set one each.
+
+`yard repo new`, `yard repo link`, and `yard slot new` do those steps one at a time.
+
+## Commands
+
+Run `yard` to see every command. These are the common ones:
+
+- `yard slot list` shows each slot, its data size, and how long the last build took. The last row is the host total.
+- `yard slot edit <name>` changes the slot file.
+- `yard slot logs <name>` reads the container log.
+- `yard settings` sets the public host, the Caddy email, and the Yard image.
+
+A terminal prints text. Any other stdout prints JSON.
+
+## Develop
+
+The server command is `python -m app.main`.
+
+```sh
+uv run pytest
+STARIO_LOOP=uvloop uv run python -m app.main
+```

staryard-0.1.0/app/__init__.py

@@ -0,0 +1,10 @@
+"""Yard. HTTP API and the yard command."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+def package_version() -> str:
+    try:
+        return version("staryard")
+    except PackageNotFoundError:
+        return "0.1.0"

staryard-0.1.0/app/__main__.py

@@ -0,0 +1,3 @@
+from app.cli import main
+
+main()

staryard-0.1.0/app/api.py

@@ -0,0 +1,337 @@
+"""JSON API. Git smart HTTP sits beside it and uses basic auth."""
+
+import json
+from dataclasses import asdict
+from typing import cast
+
+import stario.responses as responses
+from stario import App, Context, Handler, Middleware, Route, Writer
+from stario.responses import JsonValue
+
+from app.errors import YardError
+from app.podman import inspect_args
+from app.store import Experiment, Label
+from app.text import apply_slot_keys, slot_values
+from app.yard import Yard
+
+
+def register_api(app: App, yard: Yard) -> None:
+    async def health(_c: Context, w: Writer) -> None:
+        responses.empty(w, 200)
+
+    app.add(Route("GET /health"), health)
+    app.add(Route("GET /git/{path...}"), yard.serve_git)
+    app.add(Route("POST /git/{path...}"), yard.serve_git)
+
+    auth = (_bearer(yard),)
+
+    async def repos_list(_c: Context, w: Writer) -> None:
+        responses.json(w, [asdict(repo) for repo in yard.store.list_repos()])
+
+    async def repos_create(c: Context, w: Writer) -> None:
+        body = await _object(c)
+        name = body.get("name", "")
+        force = body.get("force", False)
+        if not isinstance(name, str) or not isinstance(force, bool):
+            raise YardError(400, "bad_json", "bad json")
+        responses.json(w, await yard.create_repo(name, force))
+
+    async def repos_delete(c: Context, w: Writer) -> None:
+        name = c.match.params["name"]
+        yard.delete_repo(name)
+        responses.json(w, {"name": name})
+
+    app.add(Route("GET /api/v1/repos"), repos_list, middleware=auth)
+    app.add(Route("POST /api/v1/repos"), repos_create, middleware=auth)
+    app.add(Route("DELETE /api/v1/repos/{name}"), repos_delete, middleware=auth)
+
+    async def slots_list(c: Context, w: Writer) -> None:
+        responses.json(w, await yard.list_rows(c.req.query.get("running") == "1"))
+
+    async def slots_create(c: Context, w: Writer) -> None:
+        slot, warn, note = await yard.create_slot(_string_map(await _object(c)))
+        responses.json(w, cast(JsonValue, {"values": slot_values(slot), "warnings": warn, "deploy": note}))
+
+    async def slots_get(c: Context, w: Writer) -> None:
+        responses.json(w, cast(JsonValue, slot_values(yard.store.slot(c.match.params["name"]))))
+
+    async def slots_put(c: Context, w: Writer) -> None:
+        name = c.match.params["name"]
+        edit = apply_slot_keys(yard.store.slot(name), _string_map(await _object(c)))
+        slot = await yard.update_slot(name, edit)
+        responses.json(w, cast(JsonValue, {"values": slot_values(slot), "warnings": edit.warn}))
+
+    async def slots_delete(c: Context, w: Writer) -> None:
+        name = c.match.params["name"]
+        await yard.delete_slot(name)
+        responses.json(w, {"name": name})
+
+    async def logs(c: Context, w: Writer) -> None:
+        name = c.match.params["name"]
+        tail_text = c.req.query.get("tail") or "200"
+        if not tail_text.isdigit() or int(tail_text) < 1:
+            raise YardError(400, "bad_tail", "tail must be a positive number")
+        tail = int(tail_text)
+        cursor = c.req.query.get("cursor") or ""
+        container = c.req.query.get("container") or ""
+        if c.req.query.get("follow") == "1":
+            await _follow(yard, w, name, tail, cursor, container)
+            return
+        responses.json(w, await yard.log_page(name, tail, cursor, container))
+
+    async def deploys(c: Context, w: Writer) -> None:
+        name = c.match.params["name"]
+        yard.store.slot(name)
+        limit = c.req.query.get("limit") or "0"
+        rows = yard.store.list_deploys(name, int(limit) if limit.isdigit() else 0)
+        responses.json(w, [asdict(row) for row in rows])
+
+    async def deploy(c: Context, w: Writer) -> None:
+        name = c.match.params["name"]
+        yard.store.slot(name)
+        raw = c.match.params["id"]
+        if not raw.isdigit():
+            raise YardError(400, "bad_id", "deploy id must be a number")
+        row = yard.store.deploy(int(raw))
+        if row.slot != name:
+            raise YardError(404, "not_found", "deploy does not exist")
+        responses.json(w, asdict(row))
+
+    async def inspect(c: Context, w: Writer) -> None:
+        text = await yard.podman.run(*inspect_args(c.match.params["name"]))
+        if text and not text.endswith("\n"):
+            text += "\n"
+        responses.text(w, text)
+
+    app.add(Route("GET /api/v1/slots"), slots_list, middleware=auth)
+    app.add(Route("POST /api/v1/slots"), slots_create, middleware=auth)
+    app.add(Route("GET /api/v1/slots/{name}"), slots_get, middleware=auth)
+    app.add(Route("PUT /api/v1/slots/{name}"), slots_put, middleware=auth)
+    app.add(Route("DELETE /api/v1/slots/{name}"), slots_delete, middleware=auth)
+    app.add(Route("GET /api/v1/slots/{name}/logs"), logs, middleware=auth)
+    app.add(Route("GET /api/v1/slots/{name}/deploys"), deploys, middleware=auth)
+    app.add(Route("GET /api/v1/slots/{name}/deploys/{id}"), deploy, middleware=auth)
+    app.add(Route("GET /api/v1/containers/{name}"), inspect, middleware=auth)
+
+    async def settings_get(_c: Context, w: Writer) -> None:
+        responses.json(w, asdict(yard.store.settings()))
+
+    async def settings_put(c: Context, w: Writer) -> None:
+        body = await _object(c)
+        responses.json(
+            w,
+            await yard.save_settings(
+                _optional(body, "domain"),
+                _optional(body, "email"),
+                _optional(body, "self_repo"),
+                _optional(body, "self_ref"),
+                _optional(body, "self_image"),
+            ),
+        )
+
+    app.add(Route("GET /api/v1/settings"), settings_get, middleware=auth)
+    app.add(Route("PUT /api/v1/settings"), settings_put, middleware=auth)
+
+    async def tokens_list(_c: Context, w: Writer) -> None:
+        responses.json(w, [asdict(token) for token in yard.store.list_tokens()])
+
+    async def tokens_create(c: Context, w: Writer) -> None:
+        body = await _object(c)
+        name = body.get("name", "")
+        if not isinstance(name, str):
+            raise YardError(400, "bad_json", "bad json")
+        actor = str(c.state.get("actor") or "")
+        plain = yard.store.create_token(name, actor)
+        responses.json(w, {"name": name, "token": plain, "parent": actor})
+
+    async def tokens_delete(c: Context, w: Writer) -> None:
+        name = c.match.params["name"]
+        yard.store.revoke_token(str(c.state.get("actor") or ""), name)
+        responses.json(w, {"name": name})
+
+    app.add(Route("GET /api/v1/tokens"), tokens_list, middleware=auth)
+    app.add(Route("POST /api/v1/tokens"), tokens_create, middleware=auth)
+    app.add(Route("DELETE /api/v1/tokens/{name}"), tokens_delete, middleware=auth)
+
+    async def experiments_list(c: Context, w: Writer) -> None:
+        rows = _filter_exps(yard.store.list_experiments(), c.req.query.items())
+        responses.json(w, [asdict(row) for row in rows])
+
+    async def experiments_create(c: Context, w: Writer) -> None:
+        title, body, labels = await _exp_body(c)
+        saved = yard.store.save_experiments([(False, 0, title, body, labels)], [])
+        responses.json(w, asdict(saved[0]))
+
+    async def experiments_get(c: Context, w: Writer) -> None:
+        responses.json(w, asdict(_one_exp(yard, c.match.params["id"])))
+
+    async def experiments_put(c: Context, w: Writer) -> None:
+        exp = _one_exp(yard, c.match.params["id"])
+        title, body, labels = await _exp_body(c)
+        saved = yard.store.save_experiments([(True, exp.id, title, body, labels)], [])
+        responses.json(w, asdict(saved[0]))
+
+    async def experiments_delete(c: Context, w: Writer) -> None:
+        exp = _one_exp(yard, c.match.params["id"])
+        yard.store.save_experiments([], [exp.id])
+        responses.json(w, {"id": exp.id})
+
+    app.add(Route("GET /api/v1/experiments"), experiments_list, middleware=auth)
+    app.add(Route("POST /api/v1/experiments"), experiments_create, middleware=auth)
+    app.add(Route("GET /api/v1/experiments/{id}"), experiments_get, middleware=auth)
+    app.add(Route("PUT /api/v1/experiments/{id}"), experiments_put, middleware=auth)
+    app.add(Route("DELETE /api/v1/experiments/{id}"), experiments_delete, middleware=auth)
+
+    async def hook(c: Context, w: Writer) -> None:
+        body = await _object(c)
+        repo, old, new, ref = body.get("repo", ""), body.get("old", ""), body.get("new", ""), body.get("ref", "")
+        if not all(isinstance(item, str) for item in (repo, old, new, ref)):
+            raise YardError(400, "bad_json", "bad json")
+        status, text = await yard.hook_push(repo, old, new, ref)
+        responses.text(w, text, status)
+
+    async def yard_post(c: Context, w: Writer) -> None:
+        action = (await _object(c)).get("action", "")
+        if not isinstance(action, str):
+            raise YardError(400, "bad_json", "bad json")
+        if action == "rollback":
+            await yard.rollback()
+            responses.json(w, {"image": "localhost/yard:previous", "container": "yard-swap"})
+            return
+        if action not in {"", "update"}:
+            raise YardError(400, "bad_action", "action is update or rollback")
+        responses.json(w, await yard.update_yard())
+
+    async def yard_get(_c: Context, w: Writer) -> None:
+        responses.json(w, yard.swap_status())
+
+    app.add(Route("POST /api/v1/hooks/push"), hook, middleware=auth)
+    app.add(Route("POST /api/v1/yard"), yard_post, middleware=auth)
+    app.add(Route("GET /api/v1/yard"), yard_get, middleware=auth)
+
+
+def _bearer(yard: Yard) -> Middleware:
+    def middleware(handler: Handler) -> Handler:
+        async def wrapped(c: Context, w: Writer) -> None:
+            header = c.req.headers.get("authorization") or ""
+            raw = header[7:].strip() if header.lower().startswith("bearer ") else ""
+            try:
+                token = yard.store.token_ok(raw)
+            except YardError as exc:
+                responses.json(w, {"error": {"code": exc.code, "message": exc.message}}, exc.status)
+                return
+            if token is None:
+                responses.json(w, {"error": {"code": "unauthorized", "message": "unauthorized"}}, 401)
+                return
+            c.state["actor"] = token.name
+            try:
+                await handler(c, w)
+            except YardError as exc:
+                # The writer already sent bytes. A second body would corrupt that response.
+                if not w.started:
+                    responses.json(w, {"error": {"code": exc.code, "message": exc.message}}, exc.status)
+            except Exception as exc:
+                if not w.started:
+                    responses.json(w, {"error": {"code": "internal", "message": str(exc)}}, 500)
+                else:
+                    raise
+
+        return wrapped
+
+    return middleware
+
+
+async def _follow(yard: Yard, w: Writer, name: str, tail: int, cursor: str, container: str) -> None:
+    yard.store.slot(name)
+    target = container or await yard.log_target(name)
+    args = ["logs", "--follow", "--tail", str(tail)]
+    if cursor:
+        args.extend(("--since", cursor))
+    args.append(target)
+    proc = await yard.podman.popen(*args)
+    w.headers.set("content-type", "text/plain; charset=utf-8")
+    w.write_headers(200)
+    assert proc.stdout is not None
+    try:
+        while chunk := await proc.stdout.read(8192):
+            w.write(chunk)
+    finally:
+        if proc.returncode is None:
+            proc.kill()
+        await proc.wait()
+    w.end()
+
+
+async def _object(c: Context) -> dict:
+    raw = await c.req.body()
+    try:
+        body = json.loads(raw) if raw else None
+    except json.JSONDecodeError as exc:
+        raise YardError(400, "bad_json", "bad json") from exc
+    if not isinstance(body, dict):
+        raise YardError(400, "bad_json", "bad json")
+    return body
+
+
+def _string_map(body: dict) -> dict[str, str]:
+    found: dict[str, str] = {}
+    for key, value in body.items():
+        if not isinstance(key, str) or not isinstance(value, str):
+            raise YardError(400, "bad_json", "bad json")
+        found[key] = value
+    return found
+
+
+def _optional(body: dict, key: str) -> str | None:
+    if key not in body:
+        return None
+    value = body[key]
+    if not isinstance(value, str):
+        raise YardError(400, "bad_json", "bad json")
+    return value
+
+
+def _one_exp(yard: Yard, raw: str) -> Experiment:
+    if not raw.isdigit() or int(raw) <= 0:
+        raise YardError(400, "bad_id", "experiment id must be a number")
+    exp_id = int(raw)
+    for exp in yard.store.list_experiments():
+        if exp.id == exp_id:
+            return exp
+    raise YardError(404, "not_found", "experiment does not exist")
+
+
+async def _exp_body(c: Context) -> tuple[str, str, list[Label]]:
+    body = await _object(c)
+    title = body.get("title", "")
+    text = body.get("body", "")
+    labels = body.get("labels", [])
+    if not isinstance(title, str) or not isinstance(text, str) or not isinstance(labels, list):
+        raise YardError(400, "bad_json", "bad json")
+    if not title.strip():
+        raise YardError(400, "bad_title", "a title is required")
+    parsed: list[Label] = []
+    for item in labels:
+        if not isinstance(item, dict) or not isinstance(item.get("key"), str) or not isinstance(item.get("value"), str):
+            raise YardError(400, "bad_json", "bad json")
+        parsed.append(Label(item["key"], item["value"]))
+    return title.strip(), text, parsed
+
+
+def _filter_exps(rows: list[Experiment], pairs: list[tuple[str, str]]) -> list[Experiment]:
+    want: dict[str, list[str]] = {}
+    for key, value in pairs:
+        if key == "id" or not value:
+            continue
+        want.setdefault(key, []).append(value)
+    if not want:
+        return rows
+
+    def matches(exp: Experiment) -> bool:
+        for key, values in want.items():
+            for value in values:
+                if not any(label.key == key and label.value == value for label in exp.labels):
+                    return False
+        return True
+
+    return [row for row in rows if matches(row)]