@dbx-tools/appkit-lakebox 0.0.0-stage → 0.9.131

package/scripts/lakebox-service.py

@@ -0,0 +1,449 @@
+#!/usr/bin/env python3
+"""Package-owned Lakebox service controller.
+
+Runs as one locked Lakebox user. Owns the direct-crun lifecycle for that
+user's services: saved definitions, image preparation through Buildah,
+OCI spec generation, idempotent start and stop, readiness, bounded logs, and
+restoring saved services after a Lakebox start.
+
+Commands print one JSON document on stdout. Diagnostics go to service logs.
+"""
+
+import base64
+import contextlib
+import fcntl
+import json
+import os
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import time
+
+RUNTIME = "/home/sandbox-agent/.dbx-tools/runtime"
+BUNDLE = f"{RUNTIME}/container-v1/root"
+POLICY = f"{BUNDLE}/etc/containers/policy.json"
+HOME = os.environ["HOME"]
+UID = os.getuid()
+USER_HASH = os.path.basename(os.path.realpath(HOME))
+SERVICES = f"{HOME}/.dbx-tools/services"
+STORAGE = f"{HOME}/.dbx-tools/containers"
+RUN = f"/run/lakebox/{USER_HASH}"
+CRUN_ROOT = f"{RUN}/crun"
+LOG_LIMIT = 1_048_576
+LOG_KEEP = 262_144
+HOST_BINDS = ("/usr", "/etc", "/opt", "/var", RUNTIME)
+
+
+def runtime_env():
+    return {
+        "HOME": HOME,
+        "USER": os.environ.get("USER", ""),
+        "LOGNAME": os.environ.get("USER", ""),
+        "XDG_RUNTIME_DIR": RUN,
+        "PATH": f"{BUNDLE}/usr/bin:{BUNDLE}/usr/sbin:/usr/local/bin:/usr/bin:/bin",
+        "LD_LIBRARY_PATH": f"{BUNDLE}/usr/lib/x86_64-linux-gnu:{BUNDLE}/lib/x86_64-linux-gnu"
+        f":{BUNDLE}/usr/lib/aarch64-linux-gnu:{BUNDLE}/lib/aarch64-linux-gnu",
+        "CONTAINERS_CONF": f"{BUNDLE}/usr/share/containers/containers.conf",
+        "CONTAINERS_REGISTRIES_CONF": f"{BUNDLE}/etc/containers/registries.conf",
+        "CONTAINERS_STORAGE_CONF": f"{STORAGE}/storage.conf",
+        "BUILDAH_ISOLATION": "chroot",
+    }
+
+
+def namespaced(args, log=None, check=True, capture=False):
+    """Runs one runtime command inside the user's single-UID namespace."""
+    sink = log if log is not None else subprocess.DEVNULL
+    result = subprocess.run(
+        ["unshare", "-Ur", "-m", "--", *args],
+        env=runtime_env(),
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE if capture else sink,
+        stderr=sink,
+        text=True,
+    )
+    if check and result.returncode != 0:
+        raise RuntimeError(f"{args[0]} {args[1] if len(args) > 1 else ''} exited {result.returncode}")
+    return result
+
+
+def service_dir(name):
+    return f"{SERVICES}/{name}"
+
+
+def read_definition(name):
+    with open(f"{service_dir(name)}/service.json", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def write_json(path, value):
+    temporary = f"{path}.tmp.{os.getpid()}"
+    with open(temporary, "w", encoding="utf-8") as handle:
+        json.dump(value, handle, indent=1)
+    os.replace(temporary, path)
+
+
+@contextlib.contextmanager
+def locked(name):
+    os.makedirs(service_dir(name), mode=0o700, exist_ok=True)
+    with open(f"{service_dir(name)}/.lock", "w", encoding="utf-8") as handle:
+        fcntl.flock(handle, fcntl.LOCK_EX)
+        yield
+
+
+def open_log(name):
+    path = f"{service_dir(name)}/service.log"
+    if os.path.exists(path) and os.path.getsize(path) > LOG_LIMIT:
+        with open(path, "rb") as handle:
+            handle.seek(-LOG_KEEP, os.SEEK_END)
+            tail = handle.read()
+        with open(path, "wb") as handle:
+            handle.write(tail)
+    return open(path, "a", encoding="utf-8")
+
+
+def crun_state(name):
+    result = namespaced(["crun", "--root", CRUN_ROOT, "state", container_id(name)], check=False, capture=True)
+    if result.returncode != 0:
+        return None
+    try:
+        return json.loads(result.stdout).get("status")
+    except json.JSONDecodeError:
+        return None
+
+
+def container_id(name):
+    return f"lakebox-{USER_HASH}-{name}"
+
+
+def listening_sockets():
+    """Yields (port, uid) for every listening TCP socket."""
+    for table in ("/proc/net/tcp", "/proc/net/tcp6"):
+        if not os.path.exists(table):
+            continue
+        with open(table, encoding="utf-8") as handle:
+            rows = [line.split() for line in handle.readlines()[1:]]
+        for fields in rows:
+            if fields[3] == "0A":
+                yield int(fields[1].split(":")[1], 16), int(fields[7])
+
+
+def listener_owner(port):
+    """Returns the UID listening on a loopback TCP port, or None."""
+    return next((uid for listening, uid in listening_sockets() if listening == port), None)
+
+
+def port_open(port):
+    with contextlib.suppress(OSError):
+        with socket.create_connection(("127.0.0.1", port), timeout=0.5):
+            return True
+    return False
+
+
+def ensure_storage():
+    os.makedirs(f"{STORAGE}/storage", mode=0o700, exist_ok=True)
+    os.makedirs(CRUN_ROOT, mode=0o700, exist_ok=True)
+    conf = f"{STORAGE}/storage.conf"
+    content = (
+        '[storage]\ndriver = "vfs"\n'
+        f'runroot = "{RUN}/storage"\ngraphroot = "{STORAGE}/storage"\n'
+        '[storage.options.vfs]\nignore_chown_errors = "true"\n'
+    )
+    if not os.path.exists(conf) or open(conf, encoding="utf-8").read() != content:
+        with open(conf, "w", encoding="utf-8") as handle:
+            handle.write(content)
+
+
+def prepare_image(definition, log):
+    """Pulls the image when needed and returns the rootfs plus image config."""
+    ensure_storage()
+    image = definition["image"]
+    working = f"lakebox-{definition['name']}"
+    if definition.get("pull") == "always":
+        namespaced(["buildah", "--signature-policy", POLICY, "pull", image], log)
+    marker = f"{service_dir(definition['name'])}/image.json"
+    previous = {}
+    if os.path.exists(marker):
+        with open(marker, encoding="utf-8") as handle:
+            previous = json.load(handle)
+    if previous.get("image") != image or definition.get("pull") == "always":
+        namespaced(["buildah", "rm", working], check=False)
+        log.write(f"preparing {image}\n")
+        log.flush()
+        namespaced(["buildah", "--signature-policy", POLICY, "from", "--name", working, image], log)
+    rootfs = namespaced(["buildah", "mount", working], log, capture=True).stdout.strip()
+    inspected = namespaced(["buildah", "inspect", "--type", "container", working], log, capture=True)
+    config = json.loads(inspected.stdout).get("OCIv1", {}).get("config", {})
+    write_json(marker, {"image": image})
+    return rootfs, config
+
+
+def prepare_host_rootfs(name):
+    root = f"{service_dir(name)}/rootfs"
+    for directory in ("usr", "etc", "opt", "var", "home", "run", "tmp", "proc", "sys", "dev", "root"):
+        os.makedirs(f"{root}/{directory}", exist_ok=True)
+    for link in ("bin", "sbin", "lib", "lib64"):
+        if not os.path.lexists(f"{root}/{link}"):
+            os.symlink(f"usr/{link}", f"{root}/{link}")
+    for target in (HOME, RUNTIME):
+        os.makedirs(f"{root}{target}", exist_ok=True)
+    return root
+
+
+def bind(source, target, read_only=True):
+    options = ["rbind", "ro" if read_only else "rw"]
+    return {"destination": target, "type": "bind", "source": source, "options": options}
+
+
+def service_environment(definition, image_config, host):
+    environment = dict(item.split("=", 1) for item in image_config.get("Env") or [] if "=" in item)
+    environment.setdefault("PATH", "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin")
+    if host:
+        user = os.environ.get("USER", "")
+        environment.update(HOME=HOME, USER=user, LOGNAME=user, SHELL="/bin/bash", LANG="C.UTF-8")
+    environment["TERM"] = "xterm-256color"
+    environment.update(definition.get("env") or {})
+    return [f"{key}={value}" for key, value in environment.items()]
+
+
+def service_command(definition, image_config):
+    command = definition.get("command") or [
+        *(image_config.get("Entrypoint") or []),
+        *(image_config.get("Cmd") or []),
+    ]
+    if not command:
+        raise RuntimeError("The image defines no entrypoint or command; set command")
+    return command
+
+
+def service_mounts(defaults, definition, host):
+    """Keeps the default device mounts, binds /proc and /sys, and adds service mounts."""
+    mounts = [entry for entry in defaults if entry["destination"] not in ("/proc", "/sys")]
+    for entry in mounts:
+        if entry["destination"] == "/dev/pts":
+            entry["options"] = [option for option in entry["options"] if not option.startswith("gid=")]
+    mounts.append({"destination": "/proc", "type": "bind", "source": "/proc",
+                   "options": ["rbind", "nosuid", "nodev", "noexec"]})
+    mounts.append(bind("/sys", "/sys"))
+    if host:
+        mounts.extend(bind(path, path) for path in HOST_BINDS)
+        mounts.append(bind(HOME, HOME, read_only=False))
+        mounts.append({"destination": "/tmp", "type": "tmpfs", "source": "tmpfs",
+                       "options": ["nosuid", "nodev", "mode=1777"]})
+    else:
+        mounts.extend(bind(path, path) for path in ("/etc/resolv.conf", "/etc/hosts"))
+    for mount in definition.get("mounts") or []:
+        os.makedirs(mount["source"], exist_ok=True)
+        mounts.append(bind(mount["source"], mount["target"], mount.get("readOnly", False)))
+    return mounts
+
+
+def apply_namespaces(linux, process, host):
+    """Drops network, cgroup, and UTS namespaces; host services map the real UID."""
+    namespaces = [entry for entry in linux["namespaces"] if entry["type"] not in ("network", "cgroup", "uts")]
+    if host:
+        namespaces.append({"type": "user"})
+        linux["uidMappings"] = [{"containerID": UID, "hostID": 0, "size": 1}]
+        linux["gidMappings"] = [{"containerID": UID, "hostID": 0, "size": 1}]
+        process["user"] = {"uid": UID, "gid": UID}
+    linux["namespaces"] = namespaces
+    linux.pop("cgroupsPath", None)
+    linux.pop("resources", None)
+
+
+def oci_config(definition, rootfs, image_config):
+    """Writes the OCI spec validated on FEVM for one service."""
+    directory = service_dir(definition["name"])
+    subprocess.run(["crun", "spec"], cwd=directory, env=runtime_env(), check=False,
+                   stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    with open(f"{directory}/config.json", encoding="utf-8") as handle:
+        config = json.load(handle)
+    host = definition["kind"] != "image"
+    config.pop("hostname", None)
+    config["root"] = {"path": rootfs, "readonly": host}
+    config["process"].update(
+        args=service_command(definition, image_config),
+        terminal=False,
+        env=service_environment(definition, image_config, host),
+        cwd=definition.get("workingDirectory") or (HOME if host else image_config.get("WorkingDir") or "/"),
+    )
+    apply_namespaces(config["linux"], config["process"], host)
+    config["mounts"] = service_mounts(config["mounts"], definition, host)
+    write_json(f"{directory}/config.json", config)
+
+
+def wait_ready(definition, log, deadline):
+    port = definition["port"]
+    name = definition["name"]
+    while time.time() < deadline:
+        if crun_state(name) not in ("running", "created"):
+            raise RuntimeError("The service process exited; see the service log")
+        if definition.get("readiness", "tcp") == "none":
+            return
+        owner = listener_owner(port)
+        if owner is not None and owner != UID:
+            raise RuntimeError(f"Port {port} is held by another account")
+        if owner == UID and port_open(port):
+            return
+        time.sleep(0.5)
+    raise RuntimeError(f"The service did not listen on 127.0.0.1:{port} in time")
+
+
+def stop_container(name, grace=10):
+    cid = container_id(name)
+    if crun_state(name) == "running":
+        namespaced(["crun", "--root", CRUN_ROOT, "kill", cid, "TERM"], check=False)
+        deadline = time.time() + grace
+        while time.time() < deadline and crun_state(name) == "running":
+            time.sleep(0.25)
+        namespaced(["crun", "--root", CRUN_ROOT, "kill", cid, "KILL"], check=False)
+    namespaced(["crun", "--root", CRUN_ROOT, "delete", "--force", cid], check=False)
+
+
+def write_status(name, state, error=None):
+    status = {"state": state, "updatedAt": time.time()}
+    if error:
+        status["error"] = error
+    write_json(f"{service_dir(name)}/status.json", status)
+
+
+def already_ready(definition):
+    if crun_state(definition["name"]) != "running":
+        return False
+    return definition.get("readiness", "tcp") == "none" or listener_owner(definition["port"]) == UID
+
+
+def launch(definition, log):
+    """Recreates the container from its definition and waits for readiness."""
+    name = definition["name"]
+    stop_container(name)
+    if listener_owner(definition["port"]) is not None:
+        raise RuntimeError(f"Port {definition['port']} is already in use")
+    if definition["kind"] == "image":
+        rootfs, image_config = prepare_image(definition, log)
+    else:
+        rootfs, image_config = prepare_host_rootfs(name), {}
+    oci_config(definition, rootfs, image_config)
+    namespaced(["crun", "--root", CRUN_ROOT, "create", "--bundle", service_dir(name), container_id(name)], log)
+    namespaced(["crun", "--root", CRUN_ROOT, "start", container_id(name)], log)
+    wait_ready(definition, log, time.time() + definition.get("readySeconds", 180))
+
+
+def start(name):
+    with locked(name):
+        definition = read_definition(name)
+        if already_ready(definition):
+            write_status(name, "ready")
+            return describe(name)
+        write_status(name, "starting")
+        with open_log(name) as log:
+            log.write(f"--- start {time.strftime('%Y-%m-%dT%H:%M:%S')}\n")
+            log.flush()
+            try:
+                launch(definition, log)
+            except (OSError, RuntimeError, ValueError, KeyError) as error:
+                log.write(f"--- error: {error}\n")
+                write_status(name, "error", str(error))
+                return describe(name)
+            write_status(name, "ready")
+            log.write("--- ready\n")
+    return describe(name)
+
+
+def stop(name):
+    with locked(name):
+        stop_container(name)
+        write_status(name, "stopped")
+    return describe(name)
+
+
+def remove(name):
+    if not os.path.isdir(service_dir(name)):
+        return {"removed": False}
+    with locked(name):
+        stop_container(name)
+        namespaced(["buildah", "rm", f"lakebox-{name}"], check=False)
+    shutil.rmtree(service_dir(name), ignore_errors=True)
+    return {"removed": True}
+
+
+def describe(name, include_log=False):
+    definition = read_definition(name)
+    status = {}
+    with contextlib.suppress(FileNotFoundError, json.JSONDecodeError):
+        with open(f"{service_dir(name)}/status.json", encoding="utf-8") as handle:
+            status = json.load(handle)
+    state = status.get("state", "stopped")
+    running = crun_state(name) == "running"
+    if state == "ready" and not running:
+        state = "stopped"
+    if state == "starting" and not running and not lock_held(name):
+        state = "error" if status.get("error") else "stopped"
+    result = {"name": name, "state": state, "definition": definition}
+    if status.get("error") and state == "error":
+        result["error"] = status["error"]
+    if include_log:
+        result["log"] = tail(name, 200, 16_000)
+    return result
+
+
+def lock_held(name):
+    with contextlib.suppress(FileNotFoundError):
+        with open(f"{service_dir(name)}/.lock", "w", encoding="utf-8") as handle:
+            try:
+                fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                return True
+    return False
+
+
+def names():
+    if not os.path.isdir(SERVICES):
+        return []
+    return sorted(
+        entry for entry in os.listdir(SERVICES) if os.path.exists(f"{service_dir(entry)}/service.json")
+    )
+
+
+def tail(name, max_lines, max_chars):
+    path = f"{service_dir(name)}/service.log"
+    if not os.path.exists(path):
+        return ""
+    with open(path, "rb") as handle:
+        handle.seek(0, os.SEEK_END)
+        size = handle.tell()
+        handle.seek(max(0, size - max_chars * 4))
+        text = handle.read().decode("utf-8", errors="replace")
+    return "\n".join(text.splitlines()[-max_lines:])[-max_chars:]
+
+
+def main():
+    command = sys.argv[1] if len(sys.argv) > 1 else ""
+    if command == "put":
+        definition = json.loads(base64.b64decode(sys.argv[2]))
+        name = definition["name"]
+        with locked(name):
+            write_json(f"{service_dir(name)}/service.json", definition)
+        output = describe(name)
+    elif command == "start":
+        output = start(sys.argv[2])
+    elif command == "stop":
+        output = stop(sys.argv[2])
+    elif command == "remove":
+        output = remove(sys.argv[2])
+    elif command == "list":
+        output = {"services": [describe(name, include_log=True) for name in names()]}
+    elif command == "logs":
+        output = {"log": tail(sys.argv[2], int(sys.argv[3]), int(sys.argv[4]))}
+    elif command == "start-all":
+        output = {"services": [start(name) for name in names() if read_definition(name).get("autostart")]}
+    else:
+        print("usage: lakebox-service put|start|stop|remove|list|logs|start-all", file=sys.stderr)
+        sys.exit(2)
+    json.dump(output, sys.stdout)
+
+
+if __name__ == "__main__":
+    signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+    main()

package/skills/html-page/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: html-page
+description: Deploy or host a web app, website, HTML page, Three.js scene, 3D game, visualization, or browser demo as a Lakebox service. Use when asked to deploy an app, service, site, or page and return an open URL.
+---
+
+# HTML Page
+
+Generate one complete, self-contained page; keep CSS, JavaScript, workers,
+assets, and data inline. Do not use external CDNs.
+
+When the user names an existing application, prefer its maintained Docker/OCI
+image. Use `web_search` when needed to find upstream image documentation, then
+verify unprivileged execution, `127.0.0.1:$SERVICE_PORT`, one HTTP port, and
+`$SERVICE_PATH` support. Deploy images only through
+`create_lakebox_service`; never run a container CLI directly. Use the
+self-contained page below when no compatible image exists or the user wants a
+custom browser experience.
+
+Route requests such as "deploy this app", "serve this page", "host this web
+demo", or "deploy it as a service" here when the result can run entirely in a
+browser. This includes interactive Three.js scenes and small games.
+
+Call `create_lakebox_service` once. Use a short lowercase `name` for each
+distinct page:
+
+```json
+{
+  "name": "html-page",
+  "image": "docker.io/library/python:3.12-alpine",
+  "env": { "HTML_CONTENT": "<generated page>" },
+  "command": [
+    "sh",
+    "-c",
+    "mkdir -p /site && printf %s \"$HTML_CONTENT\" > /site/index.html && exec python -m http.server \"$SERVICE_PORT\" --bind 127.0.0.1 --directory /site"
+  ]
+}
+```
+
+The call returns after the server is listening. Call it again with the same
+name to replace the page. Return the service `openUrl` as a Markdown link.

package/skills/jupyter-lab/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: jupyter-lab
+description: Deploy or run JupyterLab as a Lakebox service behind the user's authenticated route, without a separate Jupyter password or token. Use for notebook app or notebook service requests.
+---
+
+# JupyterLab
+
+Use the pinned Docker/OCI image through `create_lakebox_service`. Do not run a
+container CLI directly.
+
+Call `create_lakebox_service` once:
+
+```json
+{
+  "name": "jupyter-lab",
+  "image": "docker.io/library/python:3.12-slim",
+  "mounts": [{ "source": "notebooks", "target": "/work" }],
+  "stripPrefix": false,
+  "openPath": "lab",
+  "command": [
+    "sh",
+    "-c",
+    "[ -x /work/.venv/bin/jupyter ] || { python -m venv /work/.venv && /work/.venv/bin/pip install --quiet jupyterlab==4.4.10; } && exec /work/.venv/bin/jupyter lab --allow-root --no-browser --ip 127.0.0.1 --port \"$SERVICE_PORT\" --ServerApp.root_dir=/work --ServerApp.base_url=\"$SERVICE_PATH\" --IdentityProvider.token= --PasswordIdentityProvider.hashed_password="
+  ]
+}
+```
+
+The AppKit route supplies authentication, so do not add another token or
+password. Jupyter serves its full route path, so `stripPrefix` is false.
+Notebooks and the virtual environment persist in `~/notebooks`, so later starts
+skip installation. The first start installs JupyterLab and can take a minute.
+Return the service `openUrl` as a Markdown link.

package/skills/lakebox-showcase/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: lakebox-showcase
+description: Recommend and deploy high-value single-user Lakebox browser demos. Use when a user asks what they can do with Lakebox, wants fun Lakebox or Docker demo ideas, or needs a one-port unprivileged showcase.
+---
+
+# Lakebox Showcase
+
+For a broad question such as "what can I do with Lakebox?", recommend a short
+list before deploying anything:
+
+1. A retro desktop, paint app, or pixel-art editor built as a self-contained
+   HTML page. Use JS Paint and Piskel as design inspiration.
+2. A browser music player or sequencer inspired by Webamp or Efflux.
+3. A data-transformation workbench inspired by CyberChef or IT Tools.
+4. A diagram, drawing, or whiteboard app inspired by Excalidraw or diagrams.net.
+5. A self-contained 3D scene, puzzle, or arcade game.
+6. JupyterLab for a real stateful development environment.
+7. A network speed test for demonstrating the AppKit-to-Lakebox route.
+
+Prefer a maintained Docker/OCI image when the user names an existing
+application. If the image is not already known, use `web_search` to find the
+upstream repository or image documentation. Verify that it can run
+unprivileged, bind `127.0.0.1:$SERVICE_PORT`, expose one HTTP port, and work
+beneath `$SERVICE_PATH`. Deploy it only through `create_lakebox_service`; never
+run `docker`, `podman`, or `buildah` directly.
+
+For a custom experience, prefer the first five because browser-only code
+packaged in a small image is reliable behind the user-scoped Lakebox route. Use
+the packaged `jupyter-lab` or `network-speed-test` skill when the user selects
+one of those exact demos.
+
+Do not recommend these as primary Lakebox showcases:
+
+- PairDrop, LAN Games, or multiplayer collaboration. Lakebox routes and homes
+  are user-scoped, so cross-user interaction has little value.
+- Webtop. Lakebox already provides a built-in desktop and terminal.
+- Quake, console emulators, or ROM-based apps. Assets, licensing, device access,
+  or elevated runtime requirements make them unreliable defaults.
+- Large local ML applications such as offline translation. Model downloads and
+  memory use make the first run slow and fragile.
+- An upstream image that assumes port 80, root, a dedicated hostname, or `/`
+  asset paths. Use it only after proving that it listens on
+  `127.0.0.1:$SERVICE_PORT` and works beneath `$SERVICE_PATH`.
+
+When the user asks to deploy a showcase but does not select one, generate a
+polished self-contained retro desktop with two or three interactive mini apps.
+Replace the placeholder HTML below with the complete page, then call
+`create_lakebox_service` once:
+
+```json
+{
+  "name": "lakebox-showcase",
+  "image": "docker.io/library/python:3.12-alpine",
+  "env": {
+    "HTML_CONTENT": "<generated self-contained retro desktop page>"
+  },
+  "command": [
+    "sh",
+    "-c",
+    "mkdir -p /site && printf %s \"$HTML_CONTENT\" > /site/index.html && exec python -m http.server \"$SERVICE_PORT\" --bind 127.0.0.1 --directory /site"
+  ]
+}
+```
+
+Keep all CSS, JavaScript, assets, workers, and data inline. Do not use external
+CDNs. Return the service `openUrl` as a Markdown link.

package/skills/network-speed-test/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: network-speed-test
+description: Deploy or run a network speed-test app as a Lakebox service using LibreSpeed to measure browser-to-AppKit-to-Lakebox HTTP throughput.
+---
+
+# Network Speed Test
+
+Use the pinned Docker/OCI image through `create_lakebox_service`. Do not run a
+container CLI directly.
+
+Call `create_lakebox_service` once:
+
+```json
+{
+  "name": "speed-test",
+  "image": "docker.io/library/alpine:3.22",
+  "mounts": [{ "source": "speed-test", "target": "/app" }],
+  "command": [
+    "sh",
+    "-c",
+    "set -eu; cd /app; arch=$(uname -m); case \"$arch\" in x86_64) arch=amd64 ;; aarch64) arch=arm64 ;; esac; [ -x speedtest-backend ] || wget -qO- \"https://github.com/librespeed/speedtest-go/releases/download/v1.1.6/speedtest-go_1.1.6_linux_${arch}.tar.gz\" | tar -xz; printf 'bind_address = \"127.0.0.1\"\\nlisten_port = %s\\nserver_lat = 1\\nserver_lng = 1\\ndatabase_type = \"none\"\\n' \"$SERVICE_PORT\" > settings.toml; exec ./speedtest-backend"
+  ]
+}
+```
+
+Do not call public speed-test services or external CDNs. The result measures
+browser-to-AppKit-to-Lakebox traffic, including proxy and SSH forwarding
+overhead; it is not an ISP or raw workspace network test. Return the service
+`openUrl` as a Markdown link.

package/skills/realtime-whiteboard/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: realtime-whiteboard
+description: Deploy or run a realtime collaborative whiteboard app as a Lakebox service using WBO and user-scoped WebSocket routing.
+---
+
+# Realtime Whiteboard
+
+Use the pinned Docker/OCI image through `create_lakebox_service`. Do not run a
+container CLI directly.
+
+Call `create_lakebox_service` once:
+
+```json
+{
+  "name": "realtime-whiteboard",
+  "image": "docker.io/library/node:24-alpine",
+  "mounts": [{ "source": "whiteboard", "target": "/data" }],
+  "command": [
+    "sh",
+    "-c",
+    "set -eu; mkdir -p /data/app /data/boards; cd /data/app; [ -f server/server.mjs ] || wget -qO- https://github.com/lovasoa/whitebophir/archive/refs/tags/v2.17.1.tar.gz | tar -xz --strip-components=1; [ -d node_modules ] || npm install --omit=dev --ignore-scripts --no-audit --no-fund; WBO_HISTORY_DIR=/data/boards HOST=127.0.0.1 PORT=\"$SERVICE_PORT\" exec node server/server.mjs"
+  ]
+}
+```
+
+Boards persist in `~/whiteboard`. The first start downloads and installs WBO.
+WebSocket clients use relative URLs, so the route prefix stays intact. Return
+the service `openUrl` as a Markdown link.

package/src/_package.ts

@@ -0,0 +1,11 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Read one source or packaged resource from the appkit-lakebox package root. */
+export function readPackageResource(...segments: string[]): string {
+  const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+  const parent = dirname(moduleDirectory);
+  const packageRoot = basename(parent) === "lib" ? dirname(parent) : parent;
+  return readFileSync(join(packageRoot, ...segments), "utf8");
+}