magehand 0.1.0__tar.gz

magehand-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/

magehand-0.1.0/LICENSE

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

magehand-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: magehand
+Version: 0.1.0
+Summary: The developer CLI for building apps on davidlarrimore's homelab
+Project-URL: Source, https://github.com/davidlarrimore/magehand
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# magehand
+
+The developer CLI for building apps on [davidlarrimore](https://github.com/davidlarrimore)'s
+homelab, the same way on the owner's MacBook (Claude Code) and in OpenClaw's
+VM (its coding workers). It reads platform state and runs apps locally. It
+never deploys: changes go through pull requests.
+
+It is public because it holds nothing sensitive. Every command needs access
+that only the owner has: the private homelab repos on GitHub, the private
+`*.lab` network (home LAN or UniFi Teleport), and an authentik passkey for
+OpenBao.
+
+## Install
+
+```sh
+brew install uv            # once
+uv tool install magehand
+magehand doctor
+```
+
+Upgrade with `uv tool upgrade magehand`. You also need `gh auth login`, and
+Docker Desktop or OrbStack for database blocks. Away from home, `*.lab` needs
+Teleport and a one-time resolver file (`magehand doctor` prints it).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `magehand guide [topic]` | The app platform guide, live from homelab-apps `docs/platform/`; `magehand guide catalog` for blocks and models |
+| `magehand app [name]` | The app's blocks, every env var its pod gets and where it comes from, its URLs. In an app repo the name is the repo's |
+| `magehand login` | Sign in to OpenBao through authentik (passkey) with role `dev`: read-only access to agent apps' LiteLLM keys, 1h (8h max). The token is kept in the macOS Keychain |
+| `magehand dev up\|down\|status` | Docker containers for the app's `postgres`/`redis` blocks (the blocks' own pinned images) on a per-app network, and local values for `secret` blocks |
+| `magehand run [--no-proxy] -- CMD` | Runs CMD with the env the app's pod gets: values from its Deployment, the LLM key from OpenBao, databases from `dev up`. Precedence: manifest < the repo's `.magehand.env` (committed, non-secret overrides such as `WEB_DIR=./web`) < your shell < secrets. A proxy on `127.0.0.1:8080` adds the `X-authentik-*` headers Traefik would, as you |
+| `magehand run --container [--no-build] [-- CMD]` | Builds the repo's Dockerfile and runs the image as its pod runs: read-only, `/tmp` tmpfs, the pod's user, no capabilities, exactly the pod's env. Secrets go in as `-e NAME` only, never in the image, argv or on disk |
+| `magehand doctor` | Checks GitHub access, that `openbao.lab` is reachable, the sign-in and Docker |
+| `magehand version` | The installed version |
+
+## Development
+
+```sh
+uv venv && uv pip install -e .
+.venv/bin/python -m unittest discover -s tests
+```
+
+Python 3.9+ (the Mac's system Python works). Stdlib plus PyYAML. Releases:
+bump `version` in `pyproject.toml`, merge, then tag `vX.Y.Z`. The release
+workflow builds and publishes to PyPI through trusted publishing (no stored
+token). OpenClaw's VM installs a pinned version from homelab
+`platform/openclaw/vm/versions.env`.
+
+Never commit secrets, tokens, IP addresses or email addresses: this repo is
+public.

magehand-0.1.0/README.md

@@ -0,0 +1,52 @@
+# magehand
+
+The developer CLI for building apps on [davidlarrimore](https://github.com/davidlarrimore)'s
+homelab, the same way on the owner's MacBook (Claude Code) and in OpenClaw's
+VM (its coding workers). It reads platform state and runs apps locally. It
+never deploys: changes go through pull requests.
+
+It is public because it holds nothing sensitive. Every command needs access
+that only the owner has: the private homelab repos on GitHub, the private
+`*.lab` network (home LAN or UniFi Teleport), and an authentik passkey for
+OpenBao.
+
+## Install
+
+```sh
+brew install uv            # once
+uv tool install magehand
+magehand doctor
+```
+
+Upgrade with `uv tool upgrade magehand`. You also need `gh auth login`, and
+Docker Desktop or OrbStack for database blocks. Away from home, `*.lab` needs
+Teleport and a one-time resolver file (`magehand doctor` prints it).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `magehand guide [topic]` | The app platform guide, live from homelab-apps `docs/platform/`; `magehand guide catalog` for blocks and models |
+| `magehand app [name]` | The app's blocks, every env var its pod gets and where it comes from, its URLs. In an app repo the name is the repo's |
+| `magehand login` | Sign in to OpenBao through authentik (passkey) with role `dev`: read-only access to agent apps' LiteLLM keys, 1h (8h max). The token is kept in the macOS Keychain |
+| `magehand dev up\|down\|status` | Docker containers for the app's `postgres`/`redis` blocks (the blocks' own pinned images) on a per-app network, and local values for `secret` blocks |
+| `magehand run [--no-proxy] -- CMD` | Runs CMD with the env the app's pod gets: values from its Deployment, the LLM key from OpenBao, databases from `dev up`. Precedence: manifest < the repo's `.magehand.env` (committed, non-secret overrides such as `WEB_DIR=./web`) < your shell < secrets. A proxy on `127.0.0.1:8080` adds the `X-authentik-*` headers Traefik would, as you |
+| `magehand run --container [--no-build] [-- CMD]` | Builds the repo's Dockerfile and runs the image as its pod runs: read-only, `/tmp` tmpfs, the pod's user, no capabilities, exactly the pod's env. Secrets go in as `-e NAME` only, never in the image, argv or on disk |
+| `magehand doctor` | Checks GitHub access, that `openbao.lab` is reachable, the sign-in and Docker |
+| `magehand version` | The installed version |
+
+## Development
+
+```sh
+uv venv && uv pip install -e .
+.venv/bin/python -m unittest discover -s tests
+```
+
+Python 3.9+ (the Mac's system Python works). Stdlib plus PyYAML. Releases:
+bump `version` in `pyproject.toml`, merge, then tag `vX.Y.Z`. The release
+workflow builds and publishes to PyPI through trusted publishing (no stored
+token). OpenClaw's VM installs a pinned version from homelab
+`platform/openclaw/vm/versions.env`.
+
+Never commit secrets, tokens, IP addresses or email addresses: this repo is
+public.

magehand-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "magehand"
+version = "0.1.0"
+description = "The developer CLI for building apps on davidlarrimore's homelab"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = ["PyYAML>=6.0"]
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Source = "https://github.com/davidlarrimore/magehand"
+
+[project.scripts]
+magehand = "magehand.cli:main"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE"]

magehand-0.1.0/src/magehand/__init__.py

@@ -0,0 +1 @@
+"""magehand: the developer CLI for building apps on the homelab."""

magehand-0.1.0/src/magehand/__main__.py

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

magehand-0.1.0/src/magehand/cli.py

@@ -0,0 +1,640 @@
+"""magehand: build homelab apps from anywhere, the same way everywhere.
+
+The developer CLI for apps on the homelab, used by the owner (Claude Code on
+the MacBook) and by OpenClaw's coding workers:
+
+  magehand guide [topic]        the platform guide for apps (live from homelab-apps)
+  magehand app [name]           this app's blocks, env vars and URLs
+  magehand login                sign in to OpenBao through authentik (passkey)
+  magehand dev up|down|status   local containers for the app's postgres/redis blocks
+  magehand run [--no-proxy] -- CMD...
+                                run CMD with the env the app's pod gets; secrets
+                                come from OpenBao and local containers, never disk
+  magehand run --container [--no-build] [-- CMD...]
+                                build the repo's Dockerfile and run the image as
+                                its pod runs (read-only, non-root, no capabilities)
+  magehand doctor               check GitHub access, VPN/LAN reach, login, Docker
+  magehand version              this version (upgrade: uv tool upgrade magehand)
+
+Private by design: it talks only to GitHub and *.lab (on the LAN or over the
+VPN), never to a public homelab endpoint. Its OpenBao role `dev` can only read
+the LiteLLM keys of agent apps (homelab platform/openbao/policies/dev-read.hcl).
+"""
+import base64
+import http.client
+import http.server
+import json
+import os
+import pathlib
+import secrets
+import shutil
+import signal
+import socket
+import subprocess  # nosec B404  # runs docker, git, gh and the user's own command
+import sys
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import webbrowser
+from importlib.metadata import PackageNotFoundError, version as package_version
+
+import yaml
+
+HOMELAB_REPO = 'davidlarrimore/homelab'
+APPS_REPO = 'davidlarrimore/homelab-apps'
+OPENBAO = os.environ.get('MAGEHAND_OPENBAO', 'https://openbao.lab.davidlarrimore.com')
+LAB = 'lab.davidlarrimore.com'
+HOME = pathlib.Path.home()
+STATE = pathlib.Path(os.environ.get('XDG_STATE_HOME', HOME / '.local/state')) / 'magehand'
+CACHE = pathlib.Path(os.environ.get('XDG_CACHE_HOME', HOME / '.cache')) / 'magehand'
+KEYCHAIN_SERVICE = 'magehand'
+CALLBACK = 'http://localhost:8250/oidc/callback'
+PROXY_PORT = int(os.environ.get('MAGEHAND_PROXY_PORT', '8080'))
+# Block type -> the Secret its chart hands over (platform/building-blocks/*).
+SECRET_NAME = {'postgres': '{}-connection', 'redis': '{}-connection', 'llm': '{}-connection', 'secret': '{}'}
+
+
+def die(msg):
+    sys.exit(f'magehand: {msg}')
+
+
+# --- GitHub (read-only: the guide, app manifests, block images) ---------------
+
+def github_token():
+    token = os.environ.get('GITHUB_TOKEN') or os.environ.get('GH_TOKEN')
+    if token:
+        return token
+    if shutil.which('gh'):
+        out = subprocess.run(['gh', 'auth', 'token'], capture_output=True, text=True)  # nosec B603 B607
+        if out.returncode == 0 and out.stdout.strip():
+            return out.stdout.strip()
+    die('no GitHub access: run `gh auth login` (or set GITHUB_TOKEN)')
+
+
+def github_file(repo, path, required=True):
+    """A file on main, cached for offline use; None if it doesn't exist."""
+    cached = CACHE / repo / path
+    req = urllib.request.Request(
+        f'https://api.github.com/repos/{repo}/contents/{urllib.parse.quote(path)}?ref=main',
+        headers={'Authorization': f'Bearer {github_token()}', 'Accept': 'application/vnd.github.raw',
+                 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'magehand'})
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:  # nosec B310  # fixed https URL
+            text = resp.read().decode()
+    except urllib.error.HTTPError as error:
+        if error.code == 404:
+            if required:
+                die(f'{repo}: {path} not found on main')
+            return None
+        text = None
+    except OSError:
+        text = None
+    if text is None:
+        if cached.is_file():
+            print(f'magehand: GitHub unreachable, using the cached {path}', file=sys.stderr)
+            return cached.read_text()
+        die(f'cannot read {repo}/{path} from GitHub and nothing is cached')
+    cached.parent.mkdir(parents=True, exist_ok=True)
+    cached.write_text(text)
+    return text
+
+
+def github_dir(repo, path):
+    """Names in a directory on main ([] if it doesn't exist)."""
+    req = urllib.request.Request(
+        f'https://api.github.com/repos/{repo}/contents/{urllib.parse.quote(path)}?ref=main',
+        headers={'Authorization': f'Bearer {github_token()}', 'Accept': 'application/vnd.github+json',
+                 'User-Agent': 'magehand'})
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:  # nosec B310  # fixed https URL
+            return sorted(item['name'] for item in json.load(resp) if isinstance(item, dict))
+    except (urllib.error.HTTPError, OSError, ValueError):
+        return []
+
+
+# --- The app ------------------------------------------------------------------
+
+def current_app():
+    """The app this checkout is: an app repo is named after its app."""
+    out = subprocess.run(['git', 'remote', 'get-url', 'origin'], capture_output=True, text=True)  # nosec B603 B607
+    if out.returncode != 0:
+        die('not in a git checkout; pass the app name')
+    name = out.stdout.strip().rstrip('/').rsplit('/', 1)[-1].rsplit(':', 1)[-1]
+    name = name[:-4] if name.endswith('.git') else name
+    if name in ('homelab', 'homelab-apps'):
+        die('this is a platform repo; pass the app name')
+    return name
+
+
+def load_app(name):
+    spec = yaml.safe_load(github_file(APPS_REPO, f'apps/{name}/app.yaml')) or {}
+    services = spec.get('services') or {}
+    docs = list(yaml.safe_load_all(github_file(APPS_REPO, f'apps/{name}/base/deployment.yaml')))
+    deployment = next((d for d in docs if isinstance(d, dict) and d.get('kind') == 'Deployment'), None)
+    if not deployment:
+        die(f'apps/{name}/base/deployment.yaml has no Deployment')
+    pod = deployment['spec']['template']['spec']
+    return {'name': name, 'spec': spec, 'services': services, 'container': pod['containers'][0], 'pod': pod}
+
+
+def block_of(app, secret_name):
+    """(block name, type) whose Secret this is, or (None, None)."""
+    for name, svc in app['services'].items():
+        kind = (svc or {}).get('type')
+        if kind in SECRET_NAME and SECRET_NAME[kind].format(name) == secret_name:
+            return name, kind
+    return None, None
+
+
+def env_plan(app):
+    """[(VAR, 'value', text) | (VAR, block, type, key)] from the pod spec."""
+    plan = []
+    for item in app['container'].get('env') or []:
+        if 'value' in item:
+            plan.append((item['name'], 'value', str(item['value'])))
+            continue
+        ref = ((item.get('valueFrom') or {}).get('secretKeyRef')) or {}
+        block, kind = block_of(app, ref.get('name'))
+        plan.append((item['name'], block, kind, ref.get('key')) if block
+                    else (item['name'], 'unknown', ref.get('name') or '?'))
+    return plan
+
+
+def app_port(app):
+    for item in app['container'].get('env') or []:
+        if item.get('name') == 'PORT' and 'value' in item:
+            return int(item['value'])
+    ports = app['container'].get('ports') or []
+    return int(ports[0]['containerPort']) if ports else 8000
+
+
+# --- OpenBao (role dev: read-only LiteLLM keys) ---------------------------------
+
+def bao(method, path, token=None, body=None):
+    headers = {'Content-Type': 'application/json'}
+    if token:
+        headers['X-Vault-Token'] = token
+    req = urllib.request.Request(f'{OPENBAO}/v1/{path}', method=method, headers=headers,
+                                 data=json.dumps(body).encode() if body is not None else None)
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:  # nosec B310  # OpenBao URL (https, *.lab)
+            raw = resp.read()
+            return resp.status, (json.loads(raw) if raw.strip() else {})
+    except urllib.error.HTTPError as error:
+        return error.code, None
+    except OSError:
+        die(f'cannot reach {OPENBAO}: on the home network or the VPN? (`magehand doctor`)')
+
+
+def store_token(token, identity):
+    if sys.platform == 'darwin':
+        subprocess.run(['security', 'add-generic-password', '-U', '-s', KEYCHAIN_SERVICE,  # nosec B603 B607
+                        '-a', 'openbao-token', '-w', token], check=True, capture_output=True)
+    else:
+        STATE.mkdir(parents=True, exist_ok=True)
+        path = STATE / 'openbao-token'
+        path.touch(mode=0o600)
+        path.write_text(token)
+    STATE.mkdir(parents=True, exist_ok=True)
+    (STATE / 'identity.json').write_text(json.dumps(identity))
+
+
+def saved_token():
+    if os.environ.get('MAGEHAND_BAO_TOKEN'):
+        return os.environ['MAGEHAND_BAO_TOKEN']
+    if sys.platform == 'darwin':
+        out = subprocess.run(['security', 'find-generic-password', '-s', KEYCHAIN_SERVICE,  # nosec B603 B607
+                              '-a', 'openbao-token', '-w'], capture_output=True, text=True)
+        return out.stdout.strip() if out.returncode == 0 else None
+    path = STATE / 'openbao-token'
+    return path.read_text().strip() if path.is_file() else None
+
+
+def valid_token():
+    token = saved_token()
+    if token and bao('GET', 'auth/token/lookup-self', token)[0] == 200:
+        return token
+    die('not signed in, or the token expired: run `magehand login`')
+
+
+def identity():
+    path = STATE / 'identity.json'
+    return json.loads(path.read_text()) if path.is_file() else {}
+
+
+def cmd_login(_args):
+    status, body = bao('POST', 'auth/oidc/oidc/auth_url', body={'role': 'dev', 'redirect_uri': CALLBACK})
+    url = ((body or {}).get('data') or {}).get('auth_url')
+    if status != 200 or not url:
+        die(f'OpenBao gave no login URL (HTTP {status}); is the `dev` OIDC role set up? (scripts/setup-openbao.py)')
+    params = {}
+
+    class Callback(http.server.BaseHTTPRequestHandler):
+        def do_GET(self):
+            parsed = urllib.parse.urlparse(self.path)
+            if parsed.path != '/oidc/callback':
+                self.send_response(404)
+                self.end_headers()
+                return
+            params.update(urllib.parse.parse_qsl(parsed.query))
+            self.send_response(200)
+            self.send_header('Content-Type', 'text/plain')
+            self.end_headers()
+            self.wfile.write(b'magehand: signed in. Return to the terminal.')
+
+        def log_message(self, *args):
+            pass
+
+    with http.server.HTTPServer(('localhost', 8250), Callback) as server:
+        server.timeout = 5
+        print('Sign in through authentik in your browser (passkey)...')
+        webbrowser.open(url)
+        deadline = time.monotonic() + 300
+        while 'code' not in params and time.monotonic() < deadline:
+            server.handle_request()
+    if 'code' not in params:
+        die('sign-in timed out or was refused')
+    query = urllib.parse.urlencode({k: params[k] for k in ('state', 'code') if k in params})
+    status, body = bao('GET', f'auth/oidc/oidc/callback?{query}')
+    if status != 200:
+        die(f'OpenBao refused the sign-in (HTTP {status})')
+    auth = body['auth']
+    meta = auth.get('metadata') or {}
+    email = meta.get('email') or auth.get('display_name', '').removeprefix('oidc-')
+    who = {'email': email, 'uid': auth.get('entity_id', ''), 'username': email.split('@')[0],
+           'name': meta.get('name') or email.split('@')[0], 'groups': 'homelab-admins'}
+    store_token(auth['client_token'], who)
+    hours = auth.get('lease_duration', 3600) // 3600
+    print(f'Signed in as {email or "?"} (policy {", ".join(auth.get("policies", []))}, {hours}h).')
+
+
+# --- guide and app --------------------------------------------------------------
+
+def cmd_guide(args):
+    topics = [n[:-3] for n in github_dir(APPS_REPO, 'docs/platform') if n.endswith('.md')]
+    if not topics:  # before docs/platform exists
+        print(github_file(APPS_REPO, 'AGENTS.md'))
+        return
+    topic = args[0] if args else 'README'
+    if topic == 'catalog':
+        print(github_file(APPS_REPO, 'catalog.yaml'))
+        return
+    if topic not in topics:
+        die(f'no topic {topic!r}; topics: {", ".join(topics)}, catalog')
+    print(github_file(APPS_REPO, f'docs/platform/{topic}.md'))
+    if not args:
+        print(f'\nMore: magehand guide <topic>  ({", ".join(t for t in topics if t != "README")}, catalog)')
+
+
+def cmd_app(args):
+    app = load_app(args[0] if args else current_app())
+    name = app['name']
+    source = (app['spec'].get('source') or {}).get('repo')
+    print(f'{name}  (code: {"davidlarrimore/" + source if source else "homelab-apps apps/" + name + "/image"};'
+          f' deployment: homelab-apps apps/{name})')
+    print(f'  dev:      https://{name}-dev.{LAB}')
+    for preview in github_dir(APPS_REPO, f'previews/{name}'):
+        if preview.endswith('.yaml'):
+            print(f'  preview:  https://{name}-dev-{preview[:-5]}.{LAB}')
+    print('Blocks (app.yaml services:):')
+    if not app['services']:
+        print('  none; request one with a PR to homelab-apps apps/%s/app.yaml (`magehand guide blocks`)' % name)
+    for block, svc in app['services'].items():
+        opts = ', '.join(f'{k}={v}' for k, v in (svc or {}).items() if k != 'type')
+        print(f'  {block}: {(svc or {}).get("type")}{"  (" + opts + ")" if opts else ""}')
+    print(f'Env (the pod spec; locally: magehand run, app port {app_port(app)}):')
+    for entry in env_plan(app):
+        if entry[1] == 'value':
+            print(f'  {entry[0]} = {entry[2]}')
+        elif entry[1] == 'unknown':
+            print(f'  {entry[0]} <- Secret {entry[2]} (not a block; magehand run leaves it unset)')
+        else:
+            print(f'  {entry[0]} <- block {entry[1]} ({entry[2]}) key {entry[3]}')
+
+
+# --- local containers -------------------------------------------------------------
+
+def docker(*args, check=True):
+    if not shutil.which('docker'):
+        die('docker is required for local blocks (Docker Desktop, OrbStack or colima)')
+    return subprocess.run(['docker', *args], capture_output=True, text=True, check=check)  # nosec B603 B607
+
+
+def local_state(app_name):
+    path = STATE / f'{app_name}.json'
+    return json.loads(path.read_text()) if path.is_file() else {}
+
+
+def save_local_state(app_name, data):
+    STATE.mkdir(parents=True, exist_ok=True)
+    path = STATE / f'{app_name}.json'
+    path.touch(mode=0o600)
+    path.write_text(json.dumps(data, indent=1))
+
+
+def block_image(kind, svc):
+    values = yaml.safe_load(github_file(HOMELAB_REPO, f'platform/building-blocks/{kind}/values.yaml'))
+    if kind == 'postgres' and (svc or {}).get('vector') in (True, 'true'):
+        return values['pgvector']['image']
+    return values['image']
+
+
+def cmd_dev(args):
+    action = args[0] if args else 'status'
+    app = load_app(args[1] if len(args) > 1 else current_app())
+    state = local_state(app['name'])
+    network = f'magehand-{app["name"]}'
+    if action == 'up':  # blocks and `run --container` share it, like a namespace
+        docker('network', 'create', network, check=False)
+    for block, svc in app['services'].items():
+        kind = (svc or {}).get('type')
+        container = f'magehand-{app["name"]}-{block}'
+        if kind == 'secret' and action == 'up':
+            state.setdefault(block, {'value': secrets.token_urlsafe(36)[:48]})
+        if kind not in ('postgres', 'redis'):
+            continue
+        if action == 'down':
+            docker('rm', '-f', '-v', container, check=False)
+            state.pop(block, None)
+            print(f'{block}: removed')
+            continue
+        running = docker('inspect', '-f', '{{.State.Running}}', container, check=False).stdout.strip() == 'true'
+        if action == 'status':
+            print(f'{block} ({kind}): {"running" if running else "not running"}')
+            continue
+        if not running:
+            password = state.get(block, {}).get('password') or secrets.token_urlsafe(24)
+            docker('rm', '-f', container, check=False)
+            if kind == 'postgres':
+                docker('run', '-d', '--name', container, '--network', network, '-p', '127.0.0.1::5432',
+                       '-e', 'POSTGRES_USER=app',
+                       '-e', 'POSTGRES_DB=app', '-e', f'POSTGRES_PASSWORD={password}', block_image(kind, svc))
+            else:
+                docker('run', '-d', '--name', container, '--network', network, '-p', '127.0.0.1::6379',
+                       block_image(kind, svc),
+                       'valkey-server', '--requirepass', password, '--maxmemory', '200mb',
+                       '--maxmemory-policy', 'allkeys-lru', '--appendonly', 'yes')
+            state[block] = {'password': password}
+        inner = '5432' if kind == 'postgres' else '6379'
+        port = docker('port', container, inner).stdout.strip().splitlines()[0].rsplit(':', 1)[-1]
+        state[block]['port'] = port
+        print(f'{block} ({kind}): 127.0.0.1:{port}')
+    if action == 'up':
+        save_local_state(app['name'], state)
+    elif action == 'down':
+        (STATE / f'{app["name"]}.json').unlink(missing_ok=True)
+        docker('network', 'rm', network, check=False)
+    elif action != 'status':
+        die('usage: magehand dev up|down|status [app]')
+
+
+def local_connection(kind, block, local, app_name=None):
+    """A block's Secret keys for a local run: on the host (published port), or
+    with app_name, from a container on the app's Docker network."""
+    if block not in local:
+        die(f'block {block} ({kind}) has no local container: run `magehand dev up`')
+    conn = local[block]
+    if kind == 'secret':
+        return {'value': conn['value']}
+    pw = conn['password']
+    inner = '5432' if kind == 'postgres' else '6379'
+    host, port = (f'magehand-{app_name}-{block}', inner) if app_name else ('127.0.0.1', conn['port'])
+    if kind == 'postgres':
+        return {'host': host, 'port': port, 'username': 'app', 'database': 'app', 'password': pw,
+                'uri': f'postgresql://app:{pw}@{host}:{port}/app'}
+    return {'host': host, 'port': port, 'password': pw, 'uri': f'redis://:{pw}@{host}:{port}/0'}
+
+
+# --- run: the secrets adapter ---------------------------------------------------------
+
+def dotenv(path):
+    """KEY=VALUE lines from the repo's committed .magehand.env (local, non-secret overrides)."""
+    values = {}
+    if path.is_file():
+        for line in path.read_text().splitlines():
+            line = line.strip()
+            if line and not line.startswith('#') and '=' in line:
+                key, value = line.split('=', 1)
+                values[key.strip()] = os.path.expandvars(value.strip().strip('"\''))
+    return values
+
+
+def resolve_env(app, container=False):
+    """The pod's env, resolved for this machine. On the host, precedence is:
+    manifest values < .magehand.env < the caller's environment < secrets
+    (OpenBao, local blocks). In a container it is exactly the pod's: manifest
+    values and secrets, with blocks reached over the app's Docker network."""
+    plan = env_plan(app)
+    env = {e[0]: e[2] for e in plan if e[1] == 'value'}
+    if not container:
+        env.update(dotenv(pathlib.Path('.magehand.env')))
+        env.update({k: v for k, v in os.environ.items() if k in env})
+    local, fetched, token = local_state(app['name']), {}, None
+    for entry in plan:
+        if entry[1] in ('value', 'unknown'):
+            continue
+        var, block, kind, key = entry
+        if block not in fetched:
+            if kind == 'llm':
+                token = token or valid_token()
+                path = f'apps/data/{app["name"]}-dev/llm-{block}'
+                status, body = bao('GET', path, token)
+                if status != 200:
+                    die(f'cannot read {path} (HTTP {status}); has the broker created the key? (`magehand app`)')
+                fetched[block] = body['data']['data']
+            else:
+                fetched[block] = local_connection(kind, block, local, app['name'] if container else None)
+        if key not in fetched[block]:
+            die(f'{var}: block {block} has no key {key!r} (keys: {", ".join(sorted(fetched[block]))})')
+        env[var] = str(fetched[block][key])
+    return env
+
+
+def start_proxy(app_port_, who):
+    """127.0.0.1:PROXY_PORT -> the app, adding the X-authentik-* headers Traefik would."""
+    headers = {'X-authentik-uid': who.get('uid', 'local'), 'X-authentik-email': who.get('email', ''),
+               'X-authentik-name': who.get('name', 'Local developer'),
+               'X-authentik-username': who.get('username', 'local'), 'X-authentik-groups': who.get('groups', '')}
+
+    class Proxy(http.server.BaseHTTPRequestHandler):
+        protocol_version = 'HTTP/1.1'
+
+        def forward(self):
+            body = self.rfile.read(int(self.headers.get('Content-Length') or 0))
+            out = {k: v for k, v in self.headers.items()
+                   if not k.lower().startswith('x-authentik-') and k.lower() not in ('connection', 'host')}
+            out.update(headers)
+            out['Host'] = self.headers.get('Host', f'127.0.0.1:{PROXY_PORT}')
+            conn = http.client.HTTPConnection('127.0.0.1', app_port_, timeout=300)
+            try:
+                conn.request(self.command, self.path, body=body or None, headers=out)
+                resp = conn.getresponse()
+                data = resp.read()
+            except OSError:
+                self.send_error(502, 'app not reachable yet')
+                return
+            finally:
+                conn.close()
+            self.send_response(resp.status, resp.reason)
+            for k, v in resp.getheaders():
+                if k.lower() not in ('transfer-encoding', 'connection', 'content-length'):
+                    self.send_header(k, v)
+            self.send_header('Content-Length', str(len(data)))
+            self.end_headers()
+            self.wfile.write(data)
+
+        do_GET = do_POST = do_PUT = do_PATCH = do_DELETE = do_HEAD = do_OPTIONS = forward
+
+        def log_message(self, *args):
+            pass
+
+    server = http.server.ThreadingHTTPServer(('127.0.0.1', PROXY_PORT), Proxy)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    return server
+
+
+LAB_SUFFIX = '.' + LAB
+
+
+def lab_hosts(env):
+    """--add-host entries for the *.lab names in env values. Inside a container,
+    public DNS's 127.0.0.1 would be the container: use what the host resolves
+    (the Studio's LAN address on the MacBook) or, on the Studio, the host itself."""
+    hosts = set()
+    for value in env.values():
+        host = urllib.parse.urlparse(value).hostname if '://' in value else None
+        if host and host.endswith(LAB_SUFFIX):
+            hosts.add(host)
+    out = []
+    for host in sorted(hosts):
+        try:
+            address = socket.gethostbyname(host)
+        except OSError:
+            die(f'cannot resolve {host}: on the home network or Teleport? (`magehand doctor`)')
+        out.append(f'{host}:{"host-gateway" if address.startswith("127.") else address}')
+    return out
+
+
+def container_args(app, env, image, port, hosts, extra):
+    """docker run arguments for the app as its pod runs: read-only, non-root,
+    no capabilities. Secrets are passed by name only (-e NAME): docker reads
+    the values from its own environment, so they are never in argv or on disk."""
+    pod_sc = app['pod'].get('securityContext') or {}
+    user = f'{pod_sc.get("runAsUser", 65532)}:{pod_sc.get("runAsGroup", 65532)}'
+    args = ['run', '--rm', '--name', f'magehand-{app["name"]}-app', '--network', f'magehand-{app["name"]}',
+            '-p', f'127.0.0.1:{port}:{port}', '--read-only', '--tmpfs', '/tmp', '--user', user,  # nosec B108  # the container's own tmpfs
+            '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges']
+    if sys.stdin.isatty():
+        args.append('-it')
+    for host in hosts:
+        args += ['--add-host', host]
+    for name in sorted(env):
+        args += ['-e', name]
+    command = extra or (app['container'].get('command') or []) + (app['container'].get('args') or [])
+    if command and not extra:
+        args += ['--entrypoint', command[0], image, *command[1:]]
+    else:
+        args += [image, *command]
+    return args
+
+
+def cmd_run(args):
+    proxy = '--no-proxy' not in args
+    container = '--container' in args
+    build = '--no-build' not in args
+    args = [a for a in args if a not in ('--no-proxy', '--container', '--no-build')]
+    name = None
+    if args and args[0] == '--app':
+        name, args = args[1], args[2:]
+    if args and args[0] == '--':
+        args = args[1:]
+    if not args and not container:
+        die('usage: magehand run [--no-proxy] [--app NAME] -- CMD...   or   magehand run --container [--no-build]')
+    app = load_app(name or current_app())
+    env = resolve_env(app, container=container)
+    print(f'magehand: {app["name"]} env: {", ".join(sorted(env))}', file=sys.stderr)
+    if proxy:
+        port = int(env.get('PORT') or app_port(app))
+        start_proxy(port, identity())
+        print(f'magehand: open http://127.0.0.1:{PROXY_PORT} (signed in as '
+              f'{identity().get("email") or "local"}; the app itself listens on {port})', file=sys.stderr)
+    if container:
+        image = f'magehand/{app["name"]}:local'
+        if build:
+            print(f'magehand: docker build -t {image} .', file=sys.stderr)
+            if subprocess.run(['docker', 'build', '-t', image, '.']).returncode:  # nosec B603 B607
+                die('docker build failed')
+        docker('network', 'create', f'magehand-{app["name"]}', check=False)
+        docker('rm', '-f', f'magehand-{app["name"]}-app', check=False)
+        port = int(env.get('PORT') or app_port(app))
+        args = ['docker', *container_args(app, env, image, port, lab_hosts(env), args)]
+    child = subprocess.Popen(args, env={**os.environ, **env})  # nosec B603  # the user's own command
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        signal.signal(sig, lambda s, _f: child.send_signal(s))
+    sys.exit(child.wait())
+
+
+# --- doctor and update ---------------------------------------------------------------
+
+def cmd_doctor(_args):
+    ok = True
+
+    def check(label, passed, hint=''):
+        nonlocal ok
+        ok = ok and passed
+        print(f'{"ok  " if passed else "FAIL"} {label}{"" if passed else "  -> " + hint}')
+
+    try:
+        github_token()
+        check('GitHub access', github_file(APPS_REPO, 'catalog.yaml', required=False) is not None)
+    except SystemExit:
+        check('GitHub access', False, '`gh auth login`')
+    try:
+        reach = urllib.request.urlopen(f'{OPENBAO}/v1/sys/health', timeout=5).status == 200  # nosec B310
+    except (OSError, urllib.error.HTTPError):
+        reach = False
+    host = urllib.parse.urlparse(OPENBAO).hostname
+    try:
+        address = socket.gethostbyname(host)
+    except OSError:
+        address = None
+    if not reach and address == '127.0.0.1':
+        # Public DNS answers 127.0.0.1 for *.lab; only the home gateway (or the
+        # Studio itself) knows better. On Teleport the Mac keeps public DNS.
+        check(f'resolve {host}', False, 'public DNS answered 127.0.0.1: send *.lab lookups to the gateway once, '
+              '`echo "nameserver <gateway LAN IP>" | sudo tee /etc/resolver/lab.davidlarrimore.com` '
+              '(magehand guide local-dev)')
+    else:
+        check(f'reach {OPENBAO}', reach, f'resolved to {address or "nothing"}: on the home network or Teleport?')
+    token = saved_token()
+    check('signed in to OpenBao', bool(reach and token and bao('GET', 'auth/token/lookup-self', token)[0] == 200),
+          '`magehand login`')
+    check('docker (for postgres/redis blocks)', bool(shutil.which('docker')), 'install Docker Desktop or OrbStack')
+    sys.exit(0 if ok else 1)
+
+
+def cmd_version(_args):
+    try:
+        print(package_version('magehand'))
+    except PackageNotFoundError:
+        print('unknown (not installed as a package)')
+    print('upgrade: uv tool upgrade magehand')
+
+
+COMMANDS = {'guide': cmd_guide, 'app': cmd_app, 'login': cmd_login, 'dev': cmd_dev, 'run': cmd_run,
+            'doctor': cmd_doctor, 'version': cmd_version}
+
+
+def main():
+    if len(sys.argv) > 1 and sys.argv[1] in ('--version', '-V'):
+        sys.argv[1] = 'version'
+    if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS:
+        print(__doc__.split('Private by design')[0].strip())
+        sys.exit(0 if len(sys.argv) > 1 and sys.argv[1] in ('-h', '--help', 'help') else 2)
+    COMMANDS[sys.argv[1]](sys.argv[2:])
+
+
+if __name__ == '__main__':
+    main()

magehand-0.1.0/tests/test_cli.py

@@ -0,0 +1,204 @@
+"""Unit tests for magehand (no network, no Docker)."""
+import http.server
+import json
+import os
+import pathlib
+import socket
+import tempfile
+import threading
+import unittest
+import urllib.request
+
+from magehand import cli as magehand
+
+APP = {
+    'name': 'demo',
+    'pod': {'securityContext': {'runAsUser': 1000, 'runAsGroup': 1000}},
+    'spec': {},
+    'services': {'ai': {'type': 'llm'}, 'db': {'type': 'postgres'}, 'cache': {'type': 'redis'},
+                 'session': {'type': 'secret'}},
+    'container': {'command': ['python', '-B', '/app/app.py'], 'ports': [{'containerPort': 9000}], 'env': [
+        {'name': 'PORT', 'value': '8000'},
+        {'name': 'WEB_DIR', 'value': '/app/web'},
+        {'name': 'LLM_KEY', 'valueFrom': {'secretKeyRef': {'name': 'ai-connection', 'key': 'api_key'}}},
+        {'name': 'DATABASE_URL', 'valueFrom': {'secretKeyRef': {'name': 'db-connection', 'key': 'uri'}}},
+        {'name': 'REDIS_URL', 'valueFrom': {'secretKeyRef': {'name': 'cache-connection', 'key': 'uri'}}},
+        {'name': 'SESSION_KEY', 'valueFrom': {'secretKeyRef': {'name': 'session', 'key': 'value'}}},
+        {'name': 'OTHER', 'valueFrom': {'secretKeyRef': {'name': 'handmade', 'key': 'x'}}},
+    ]},
+}
+LOCAL = {'db': {'password': 'pw', 'port': '5555'}, 'cache': {'password': 'rpw', 'port': '6666'},
+         'session': {'value': 'v' * 48}}
+
+
+def free_port():
+    with socket.socket() as s:
+        s.bind(('127.0.0.1', 0))
+        return s.getsockname()[1]
+
+
+class Plan(unittest.TestCase):
+    def test_env_plan(self):
+        plan = {e[0]: e[1:] for e in magehand.env_plan(APP)}
+        self.assertEqual(plan['PORT'], ('value', '8000'))
+        self.assertEqual(plan['LLM_KEY'], ('ai', 'llm', 'api_key'))
+        self.assertEqual(plan['DATABASE_URL'], ('db', 'postgres', 'uri'))
+        self.assertEqual(plan['SESSION_KEY'], ('session', 'secret', 'value'))
+        self.assertEqual(plan['OTHER'], ('unknown', 'handmade'))
+
+    def test_app_port(self):
+        self.assertEqual(magehand.app_port(APP), 8000)
+        no_port_env = {**APP, 'container': {'ports': [{'containerPort': 9000}], 'env': []}}
+        self.assertEqual(magehand.app_port(no_port_env), 9000)
+
+    def test_local_connection(self):
+        pg = magehand.local_connection('postgres', 'db', LOCAL)
+        self.assertEqual(pg['uri'], 'postgresql://app:pw@127.0.0.1:5555/app')
+        self.assertEqual(magehand.local_connection('redis', 'cache', LOCAL)['uri'], 'redis://:rpw@127.0.0.1:6666/0')
+        with self.assertRaises(SystemExit):
+            magehand.local_connection('postgres', 'db', {})
+
+
+class Resolve(unittest.TestCase):
+    def setUp(self):
+        self.saved = (magehand.bao, magehand.valid_token, magehand.local_state)
+        self.paths = []
+        magehand.valid_token = lambda: 'tok'
+        magehand.local_state = lambda _name: LOCAL
+
+        def fake_bao(method, path, token=None, body=None):
+            self.paths.append(path)
+            return 200, {'data': {'data': {'api_key': 'sk-test', 'base_url': 'https://llm.lab/v1'}}}
+        magehand.bao = fake_bao
+        self.cwd = os.getcwd()
+        self.tmp = tempfile.TemporaryDirectory()
+        os.chdir(self.tmp.name)
+
+    def tearDown(self):
+        magehand.bao, magehand.valid_token, magehand.local_state = self.saved
+        os.chdir(self.cwd)
+        self.tmp.cleanup()
+        os.environ.pop('PORT', None)
+
+    def test_resolves_every_source(self):
+        env = magehand.resolve_env(APP)
+        self.assertEqual(env['LLM_KEY'], 'sk-test')
+        self.assertEqual(env['DATABASE_URL'], 'postgresql://app:pw@127.0.0.1:5555/app')
+        self.assertEqual(env['SESSION_KEY'], 'v' * 48)
+        self.assertNotIn('OTHER', env)
+        self.assertEqual(self.paths, ['apps/data/demo-dev/llm-ai'])
+
+    def test_precedence(self):
+        pathlib.Path('.magehand.env').write_text('# local\nWEB_DIR=./web\nPORT=7000\n')
+        os.environ['PORT'] = '7100'
+        env = magehand.resolve_env(APP)
+        self.assertEqual(env['WEB_DIR'], './web')     # .magehand.env over the manifest
+        self.assertEqual(env['PORT'], '7100')         # the caller's environment over both
+
+    def test_container_mode_is_exactly_the_pod(self):
+        pathlib.Path('.magehand.env').write_text('WEB_DIR=./web\n')
+        os.environ['PORT'] = '7100'
+        env = magehand.resolve_env(APP, container=True)
+        self.assertEqual(env['WEB_DIR'], '/app/web')  # no host overrides
+        self.assertEqual(env['PORT'], '8000')
+        self.assertEqual(env['DATABASE_URL'], 'postgresql://app:pw@magehand-demo-db:5432/app')
+        self.assertEqual(env['REDIS_URL'], 'redis://:rpw@magehand-demo-cache:6379/0')
+
+    def test_missing_key_fails(self):
+        bad = {**APP, 'container': {'env': [
+            {'name': 'X', 'valueFrom': {'secretKeyRef': {'name': 'ai-connection', 'key': 'nope'}}}]}}
+        with self.assertRaises(SystemExit):
+            magehand.resolve_env(bad)
+
+
+class Container(unittest.TestCase):
+    def test_hardened_and_secrets_by_name_only(self):
+        env = {'LLM_KEY': 'sk-secret', 'PORT': '8000'}
+        args = magehand.container_args(APP, env, 'magehand/demo:local', 8000, ['llm.lab.davidlarrimore.com:192.0.2.5'], [])
+        joined = ' '.join(args)
+        self.assertNotIn('sk-secret', joined)
+        self.assertIn('-e LLM_KEY', joined)
+        for flag in ('--read-only', '--cap-drop ALL', '--security-opt no-new-privileges', '--user 1000:1000',
+                     '-p 127.0.0.1:8000:8000', '--network magehand-demo',
+                     '--add-host llm.lab.davidlarrimore.com:192.0.2.5'):
+            self.assertIn(flag, joined)
+        self.assertEqual(args[args.index('--entrypoint') + 1:], ['python', 'magehand/demo:local', '-B', '/app/app.py'])
+
+    def test_explicit_command_replaces_the_pods(self):
+        args = magehand.container_args(APP, {}, 'img', 8000, [], ['sh', '-c', 'true'])
+        self.assertNotIn('--entrypoint', args)
+        self.assertEqual(args[-4:], ['img', 'sh', '-c', 'true'])
+
+    def test_lab_hosts(self):
+        saved = magehand.socket.gethostbyname
+        magehand.socket.gethostbyname = lambda h: '127.0.0.1' if h.startswith('llm.') else '192.0.2.7'
+        try:
+            hosts = magehand.lab_hosts({'A': 'https://llm.lab.davidlarrimore.com/v1',
+                                        'B': 'https://x.lab.davidlarrimore.com', 'C': 'https://example.com', 'D': 'plain'})
+        finally:
+            magehand.socket.gethostbyname = saved
+        self.assertEqual(hosts, ['llm.lab.davidlarrimore.com:host-gateway', 'x.lab.davidlarrimore.com:192.0.2.7'])
+
+
+class Doctor(unittest.TestCase):
+    def test_lab_resolving_to_localhost_suggests_the_resolver(self):
+        import contextlib
+        import io
+        saved = (magehand.urllib.request.urlopen, magehand.socket.gethostbyname, magehand.github_token,
+                 magehand.github_file, magehand.saved_token)
+
+        def no_route(*_a, **_k):
+            raise OSError('connection refused')
+        magehand.urllib.request.urlopen = no_route
+        magehand.socket.gethostbyname = lambda _h: '127.0.0.1'
+        magehand.github_token = lambda: 't'
+        magehand.github_file = lambda *_a, **_k: 'x'
+        magehand.saved_token = lambda: None
+        out = io.StringIO()
+        try:
+            with contextlib.redirect_stdout(out), self.assertRaises(SystemExit):
+                magehand.cmd_doctor([])
+        finally:
+            (magehand.urllib.request.urlopen, magehand.socket.gethostbyname, magehand.github_token,
+             magehand.github_file, magehand.saved_token) = saved
+        self.assertIn('/etc/resolver/lab.davidlarrimore.com', out.getvalue())
+
+
+class ProxyHeaders(unittest.TestCase):
+    def test_injects_identity_and_strips_client_headers(self):
+        seen = {}
+
+        class Echo(http.server.BaseHTTPRequestHandler):
+            def do_GET(self):
+                seen.update({k.lower(): v for k, v in self.headers.items()})
+                body = b'ok'
+                self.send_response(200)
+                self.send_header('Content-Length', str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+
+            def log_message(self, *args):
+                pass
+
+        backend = http.server.HTTPServer(('127.0.0.1', 0), Echo)
+        threading.Thread(target=backend.serve_forever, daemon=True).start()
+        magehand.PROXY_PORT = free_port()
+        proxy = magehand.start_proxy(backend.server_address[1], {'email': 'me@example.com', 'uid': 'u1',
+                                                                 'username': 'me', 'groups': 'homelab-admins'})
+        try:
+            req = urllib.request.Request(f'http://127.0.0.1:{magehand.PROXY_PORT}/x',
+                                         headers={'X-authentik-email': 'forged@example.com'})
+            with urllib.request.urlopen(req, timeout=5) as resp:  # nosec B310  # local test server
+                self.assertEqual(resp.read(), b'ok')
+        finally:
+            proxy.shutdown()
+            proxy.server_close()
+            backend.shutdown()
+            backend.server_close()
+        self.assertEqual(seen['x-authentik-email'], 'me@example.com')
+        self.assertEqual(seen['x-authentik-uid'], 'u1')
+        self.assertEqual(seen['x-authentik-groups'], 'homelab-admins')
+
+
+if __name__ == '__main__':
+    unittest.main()